
Lisa Systems Software 



I k^ndoM^ 



File Edit Search Type Style Print Markers 



Clipboard 
V-#2#2-Hemisphere.TEXT 



-#2#2-Stretch.TEXT 



-#2#2-Stretch.TEXT 



BEGIN { main program } 

{ IrLitialization - Generic to all applications usin^ QuickDraw 

QDInit(@heapBuf, @heapBuf[8192], (?>heapError]; 

OpenPort((?)myPort) ; 
PaintB.ect(thePort\portE.ect) ; 
Initlcons; {moved to here from below stuff hex} 
InitScales; {moved to here from telow stuffhex} 

DrawStuff; 

REPEAT UKTIL KeyBdEvent(FALSE,FALSE,event] AND 

(event.ascii <> CHR[1]]; 



PaintRect(thePort" .portRect]; 

SetRect(srcRect,0,0,720,360); 

my Picture := OpenPicture(srcRect3; 

DrawStuff: 
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PROCEDURE DrawFigure(viewflng, rollflng, pitchfing : 

BEGIN 

viewflngie(viewflng); 

Identity; 

Roll(rollflng); 

Pitch(pitchflng): 

EraseR€ct(portr .portRect); 

FraneRectCportr .portRect): 

PlotGrid; 
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This manual and the software described in it are copyrighted with all rights 
reserved. Under the copyright laws, this manual or the software may not be 
copied, in whole or in part, without the written consent of Apple, except in 
the normal use of the software or to make a backup copy. The same 
proprietary and copyright notices must be affixed to any permitted copies as 
were affixed to the original. This exception does not allow copies to be 
made for others, whether or not sold, but all the material purchased (with all 
backup copies) may be sold, given, or loaned to another person. Under the 
law, copying includes translating into another language or format. 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a multiuse license may 
be purchased to allow the software to be used on more than one computer 
owned by the purchaser, including a shared-disk system. (Contact your 
authorized Apple dealer for information on multiuse licenses.) 



Licensing Retyjiren^nits for Software Developers 

Apple has a low-cost licensing program, which permits developers of 
softwai'e for the Lisa to incorporate Apple-developed libraries and object 
codes into their products. Both in-house and external distribution require a 
license. Before distributing any products that incorporate Apple software, 
please contact Software Licensing at the address below for both licensing and 
technical information. 
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Computer, Inc. 
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Limited Warranty on Kfedia and Manuals 

If you discover physical defects in the media on which this software is 
distributed, or in the manuals distributed with the software, Apple will 
replace the media or manuals at. no charge to you, provided you return the 
item to be replaced with proof of purchase to Apple or an authorized Apple 
dealer during the 90-day period after you purchased the software. In some 
countries the replacement period may be different; check with your 
authorized Apple dealer. 

ALL IMPLIED WARRANTIES ON THE MEDIA AND MANUAL, INCLUDING 
IMPUED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) DAYS 
FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THE 
PRODUCT- 

Even though Apple has tested the software and reviewed the documentation, 
APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS 
OR IMPLIED, WITH RESPECT TO THIS SOFTWARE, ITS QUALITY, 
PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR 
PURPOSE. AS A RESULT, THIS SOFTWARE IS SOLD "AS IS," AND YOU, 
THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY 
AND PERFORMANCE- 

IN NO EVENT WILL APPLE BE HELD UABLE FOR DIRECT, INDIRECT, 
SPEaAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM 
ANY DEFECT IN THE SOFTWARE OR ITS DOCUMENTATION, even if advised 
of the possibility of such damages. In particular, Apple shall have no 
liability for any programs or data stored in or used with Apple products, 
including the costs of recovering such programs or data. 

THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND 
DM LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No 

Apple dealer, agent, or employee is authorized to make any modification, 
extension, or addition to this warranty. 

Some states do not allow the exclusion or limitation of implied warranties or 
liability for incidental or consequential damages, so the above limitation or 
exclusion ma,/ not apply to you. This warranty gives you specific legal 
rights, and you may also have other rights which vary from state to state. 
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This binder contains seven documents about the Lisa"* system software for 
programmers' reference. The manuals are, in order: 

■ Operating S^^siem Reference Msnual for the Lisa. 

■ The OEMS^^call Unit 

■ The Stesidard fpple Numeric Environment. 

■ The 680O0 f^issembly-Language S^NE. 

■ The StdUnit. 

■ The ProgComm Unit. 

- The QuickPort Programmer's Guide. 

In addition, elsewhere in this package of books and media, there is a copy of 
Motorola's MSdOOO 16/12 Bit Microprocessor Programme's Reference Manual. 
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The Contents of TTtfs Manual 

This marwal describes the Operating System service calls that are available to 
Pascal and assembler programs. It is written for experienced Pascal 
programmers arwl does not explain elementary terms and programming 
techniques. We assume that you have read the Lisa Owner's Guide and 
Workshop User's Guide for the Lisa and are familiar with your Lisa system. 

Chapter l is a general introduction to the operating system. 

Chapter 2 describes the File System and the available File System calls. This 
includes a description of the interprocess communication facility, pipes, and 
the Operating System calls that allow processes to use pipes. 

Chapter 3 describes the calls available to control processes, and also describes 
the structure of processes. 

Chapter a describes how processes can control their use of available memory. 

Chapter 5 describes the use of events and exceptions that control process 
synchronization, it also describes the use of the system clock. 

Chapter 6 describes the calls you can use to find out about the configuration 
of the system. 

Appendix A contains the source text of syscall, the unit that contains the 
type, procedure, and function definitions discussed in this manual. 

Appendix B contains a list of system-reserved exception names. 

Appendix c contains a list of system-reserved event names. 

Appendix D contains a list of error messages that can be produced by the 
calls documented in this manual. 

Appendix E contains a description of the information you can obtain from the 
Operating System sdsout files and devices. 

Type and Syntax Conventions 

Bold-face type is used in this manual to distinguish programming keywords and 
constructs from English text. For example, FLUSH is the name of a system 
call. System call names are capitalized in this manual, although Pascal does 
not distinguish between lower and upper case characters. Italics indicate a 
new term whose explanation follows. 



Future Releases 

A few features of the Lisa Operating System will t)e changed in future 
releases: 

• Pipes will not be supported. 

• Timed events will not be supported 

• Configuration System Calls will be changed. 

If you want your software to be upward-compatible^ please take these changes 
into consideration. More information Is provided in the appropriate sections 
of the manual. 
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The Operating System (OS) provides ai environment in which multiple processes 
can coexist, communicate, and share data. It provides a file system for I/O 
and information storage, handles exceptions (software interrupts), aid performs 
memory management 

H The Main Functions 

This chapter describes the four main functional areas of the OS: the File 
System, process management, memory management, and event and exception 
handling. 

The File System provides input and output. The File System accesses devices, 
volumes, and files. Each object, whether a printer, disk file, or any other type 
of object, is referenced by a pathname. Every I/O operation is performed as 
an uninterpreted byte stream. Using the File System, all I/O is device 
independent. The File System also provides device-specific control operations. 

A process consists of an executing program and its associated data Several 
processes can execute concurrently by multiplexing the processor between 
them. These processes can be broken into segments which are automatically 
swapped into memory as needed. 

Memory management routines handle data segments. A data segment is a file 
that can be placed in memory and accessed directly. 

Exceptions and events are process-communication constructs provided by the 
OS. An event Is a message sent from one process to another, or fron a 
process to itself, that is delivered to the receiving process only when the 
process asks for that event. An exception is a special type of event that 
forces itself on the receiving process. There is a set of system-defined 
exceptions (errors), and programs can define their own. System errors such as 
division by zero are examples of system-defined exceptions. You can use the 
system calls provided to define any exceptions you want. 

1.2 Using the OS Functions 

Both built-in language features and explicit OS system calls can access OS 
routines to perform desired functions. For example, the Pascal writeln 
procedure is a built-in feature of the language. The code to execute writeln 
Is supplied in lOSPASLIB, the Pascal run-time sqDport routines library. This 
code, which is added to the program when the program is linked, calls OS 
File System routines to perform the desired output. 

You can also call OS routines explicitly. This Is usually done when the 
language does not provide the operation you want. OS routines allow Pascal 
programs, for example, to create new processes, which could not otherwise be 
done, since Pascal does not have any built-in process-handling functions. 
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N\ calls to the OS are synchronous, which means they do not return until the 
operation is complete. Each call returns an error code to indicate if anything 
went wrong during the operatioa Any non-zero value indicates an enor or 
warning. Negative error codes indicate warnings. For a list of error codes 
and their meaning, see Appendix D. 

13 TTe File System 

The File System performs all I/O as uninterpreted byte streams. These Dyte 
streams can go to files on disk or to other devices such as a printer or an 
alternative console. In all cases, the device or file has a File System name. 
Except for device-control functions, the File System treats devices and files 
in the sane way. 

The File System allows sharing of all types of objects. 

The File system provides for naming objects (devices, files, etc.). A name in 
the File System is called a patrmama A complete pathname consists of a 
directory name and a file name. The file name is meaningful only for storage 
devices (devices that store byte streams for later use, such as dlsks> 

Each process has a working directory associated with it. This allows you to 
reference objects with an incomplete pathname. To access an object in the 
working directory, you specify Its file name. To access an object in a 
different directory, you specify its complete pathname. 

Before a device can be accessed. It must be mounted. Devices can be 
mounted using the Preferences tool or by using the MOLMT call. See Chapter 
2 for an explanation of this call and other File System calls. If the device is 
a storage device, the mount operation makes a volume name available. A 
volume name Is a logical name for a disk, and is saved on the disk itself. The 
rmount operation logically connects the volume to the system, so that the files 
on the volume may be accessed. The volume name can replace a device name 
in a pathname used to access an object on the disk. The volume name allows 
you to access a file with the same pathname no matter where the drive is 
actually connected. 

A device can be accessed if it is specified in the configuration list created by 
the Preferences tool, is physically connected to the Lisa, and is mounted. 
There are some operations that can be performed on unmounted devices. Two 
examples are DEVICE_CONTROL calls and scavenging. Logically mounting a 
volume on a device makes file access to the volume possible. For storage 
devices, a volume is an actual magnetic medium that can contain recorded 
files. For non-storage devices, volumes and files are concepts used to 
maintain a uniform interface. Files on non-storage devices such as printers 
do not store data but act as ports for performing 1/0 to the devices. 
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The basic operations provided Xsi the File System are as follows: 

mount and unmount - make a volume accessible/Inaccessible 
open and close - make an object accessible/inaccessible 
read and write - transfer Information to and from an object 
device control functions - control device-specific functions 

Some operations apply only to storage devices: 

allocate and deallocate - specify size of an object 

manipulate catalog - control naming of objects and creation and 

destruction of objects 
manipulate attributes - look at or change the characteristics of 

the object 

In addition to the data in an object, the object itself has certain 
characteristics called attrHxites, such as the length and creation date of a 
file. Calls are available to access the attributes of any File System object In 
addition to Its system-defined attributes, an object on a storage device can 
have a latjel The label is available for programs to store information that 
they can interpret 

Non-storage devices such as printers are accessed with a limited set of 
operations. They must be mounted and opened before they can be accessed. 
Seqi^ntial read and/or write (^rations are available as appropriate for the 
device. Device-control functions are available to perform any device- 
specific functions needed. The file-name portion of the complete pathname 
for a non-storage device is not used by the File System, although you do have 
to provide one when you open the device. 

For storage devices, the same sequential read and write operations are valid 
as for non-storage devices, storage devices also must be mounted, and 
particular files opened, before the files can be used. They have appropriate 
device-control functions available. 

When writing to a disk file, space for the file is allocated as needed. Space 
for a file does not need to be contiguous, and in some cases this automatic 
allocation can result in a fragmented file, which may slow file access. To 
insure r^id access, you can pre-allccate spaje for the file. Pre-allocating 
the file also ensures that the process will not run out of space on the disk. 

Four types of objects can be stored on storage devices. These are files, pipes, 
data segments, and event channels. Files, already discussed, are simply arrays 
of stored data Pipes are objects that provide Interprocess communlcatloa 
Data segments are special cases of files that are loaded Into memory along 
with program code. Event channels are pipes with a specialized structure 
Imposed by the system. 

L4 Process Management 

A process is an executing program and the data associated with It Several 
processes car) exist at or» time, ar^l they appear to run sirmiltsneously 
because the CPU is multiplexed among them. The Scheduler decides what 
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process should use the CPU at any one time, it uses a generally non- 
preemptive scheduling algorithm. This means that a process will not lose the 
CPU unless It Dlocks. The blocked state is explained later in this section. 

A process can lose the CPU when one of the following happens: 

• The process calls an operating System procedure or function. 

• The process references one of its code segments that Is not currently in 
memory. 

If neither of these occur^ the process will not lose the CPU. 

Every process is started by another process. The newly started process is 
called the son process The process that started it is called its father process 
The resulting structure is a tree of processes. See Figure 3-2 for an 
illustration of a process tree. 

When any process terminates^ all its son processes and their descendants are 
also terminated. 

When the OS is booted^ it starts a shell process The shell process starts any 
other processes desired by the user. 

Every newly created process has the same system-standard attributes and 
capabilities. These can be changed Xi'j using system calls. 

Any processes can suspend^ activate, or kill any other process for which the 
global ID is known, as long as the other process does not protect Itself. 

The memory accesses of an executing process are restricted to its own 
memory address space. Processes can communicate with other processes by 
using shared files, pipes, event channels, or shared data segments. 

A process can be in one of three states: ready, running, or blocked. A ready 
process \% waiting for the Scheduler to select it to run. A running process \% 
currently using the CPU to execute its code. A blocked process \% waiting for 
some event, such as the completion of an I/O operation. It will not be 
scheduled until the event occurs, at which point it becomes ready. A 
terminated processX\a& finished executing. 

Each process has a priority from 1 to 255. The higher the number, the higher 
the priority of the process. Priorities 226 to 255 are reserved for system 
processes. The scheduler always runs the ready process with the highest 
priority. A process can change its own priority, or the priority of any other 
process, while It is executing. 

13 Memory Management 

Memory managment is concerned with what is in physical memory at any one 
time. Each process can use up to 128 memory segments. Each segment can 
contain up to 128 Kbytes. Memory segments are of two types: code segments 
and data segments. The total amount of memory used by any one process can 
exceed the available RAM of the Lisa The Operating System will swap code 
segments in and out of memory as they are needed. To aid the Operating 
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System in swapping data segments^ calls are provided to give programs the 
ability to define which data segments must be in memory while a particular 
part of the program is executing. 

You have control of how your program is divided up. For executable code 
segments, you use the segmentation commands of the Pascal compiler to break 
the program in pieces. 

In addition to residing in memory^ data segments can be stored permanently 
on disk. They can be accessed with calls similar to File System calls. This 
allows you to use a data segment as a direct-access file—a file that is 
accessed as part of your memory space. 

Calls are provided for making, killing, opening, and closing data segments. 
You can also change the size of a data segment and set its access mode to 
read-only or read-write, in addition, you can make a permanent disk copy of 
the contents of a data segment at any lime. Other calls give you ability to 
force the contents of the data segment to be swapped into main memory so 
they can be accessed by your process. 

1^ Exceptions and Events 

An exception is an unexpected condition in the execution of a process (an 
interrupt). An event is a message from another process. 

An exception can be generated either by the system or by an executing 
program. System exceptions are generated by various sorts of errors such as 
divide by zero. Illegal Instruction, and Illegal address. System exception 
handlers are supplied that terminate the process. You can write your own 
exception handlers for any of these exceptions If you want to try to recover 
from the error. 

User exceptions can be declared and exception handlers can be written to 
process them. Your program can then signal this new exception. 

Events are messages sent from one process to another. They are sent through 
event channels. 

A process that expects a message from an event channel executes a call to 
wait for an event on that channel. This will give It the next message, if one 
exists, or block the process until a message arrives. 

If a process wants to know when an event arrives, but does not want to wait 
for it. It can use an event-call channel. This is set up by associating a user 
exception with the event channel when It Is opened. The Operating System 
win then Invoke the corresponding user exception handler whenever a message 
anlves In the event channel. 

1.7 Interprocess communication 

There are four methods for Interprocess communication: shared files, pipes, 
event channels, and shared data segments. 
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Shared files are used for high volume transfers of Information. It Is necessary 
to coordinate the processes somehow to prevent them from overwriting each 
other's Information. 

Pipes are used for communication between processes with an uninterpreted 
dyte stream. (Note that pipes will not de supported in future releases of the 
Operatlr^ System.) The pipe mechanism provlctes for the needed 
synchronization; a process will block if it Is trying to read from an empty 
pipe or write to a full one, A read from a pipe consumes the information^ so 
it is no longer available. Only one process can read from a given pipe. 

Event channels are similar to pipes, except that event channels transmit short, 
structured messages Instead of uninterpreted bytes. 

A shared data segment can be used to transmit a large amount of data 
rapidly. Having a shared data segment means that this data segment Is In the 
memory address space of all the processes that want to use it All the 
processes can then directly read and write Infomnation in the data segment. 
It Is necessary to provide some sort of synchronization to keep one process 
from overwriting another's Information. 

1.8 Using the 06 Interface 

The interface to all the system calls is provided in the syscall unit, found in 
Appendix A. This unit can be used to provide access to the calls. See the 
Workshop user's Guide for tfie Lisa for more Information on using Syscall. 

1.9 Running Programs under the 08 

Programs can be written and run by using the Workshop, which provides 
program development tools such as editing and debugging facilities. 

1.10 Writing Programs That Use the OS 

You can write a program that calls OS routines to perform needed functions. 
This program uses the Syscdll unit and then calls the routines needed. 
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The File System provides device-independent I/O^ storage with access 
protection^ and uniform file-naming conventions. 

Device independence means that all I/O is performed In the same way, 
whether the ultimate destination or source is disk storage^ another program, a 
printer, or anything else. In all cases, W is performed to or from /2/PX 
although those files can also be devices, data segments, or programs. 

Every file is an uninterpreted stream of eight-bit bytes. 

A file that is stored on a block-structured device, such as a disk, is listed in 
a catalog {^\zo called a cfJrectorj) and has a name. For each such file the 
catalog contains an entry describing the file's attributes^ including the length 
of the file, its position on the disk, and the last backup copy date. Arbitrary 
application-defined information can be stored in an area called the flJe laOel 
Each file has two associated measures of length, the Logical End of File 
(LEOF) and the Physical End of File (PECF) The LEOF is a pointer to the last 
byte that has meaningful data. The PECF is a count of the number of blocks 
allocated to the file. The pointer to the next byte to be read or written is 
called the file marker. 

Since I/O is device independent, application programs do not have to take 
account of the physical characteristics of a device. However, on block- 
structured devices, programs can make I/O requests in whole-block increments 
in order to improve program performance. 

All input and output is synchronous in that the I/O requested is performed 
before the call returns. The actual I/O, however, is asynchronous, in that 
processes may block when performing I/a See Section 3.5, Process Scheduling, 
for more information on blocking. 

To reduce the Impact of an error, the File System maintains distributed, 
redundant information about the files on storage devices. Duplicate copies of 
critical information are stored in different forms and in different places on 
the media. All the files are able to identify and describe themselves, and 
there are usually several ways to recover lost information. The Scavenger 
utility is able to reconstruct damaged catalogs from the information stored 
with each file. 

2.1 File Names 

/Ml the files known to the Operating System at a particular time are organized 
into catalogs. Each disk volume has a catalog that lists all the files on the 
disk. 

/\ny object catalogued in the File System can be named by specifying the 
volume on which the file resides and the file name. The names are separated 
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by the character '*-'*. Because the top catalog in the system has no name, all 
complete pathnames begin with "-'*. 

For example^ 

-LISA-FORMAT. TEXT 

refers to a file naned FORMAT. TEXT on a volume named LISA. The file 
name can contain up to 32 characters. If a longer name is specified, the 
name is truncated to 32 characten. Accesses to sequential devices use an 
arbitrary dummy filename that Is ignored but must be present In the 
pathname. For example, the serial port pathname 

-RS232B 

Is Insufficient, but 

-RS232B-XYZ 

is accepted, even though the -XYZ portion is Ignored. Certain device names 
are predefined: 

RS232A serial Port A 

RS232B Serial Port B 

PARAPORT Parallel Port 

SLOTxCHANy Serial ports: x is l, 2, or 3 and y is l or 2 

MAINCONSOLE wTiteln and readln device 

ALTCONSOLE writelD and readln device 

UPPER upper Diskette drive (Drive i) 

LOWER Lower Diskette drive (Drive 2) 

BITBKT Bit bucket: data Is thrown away when directed here 

See Chapter 6 for more information on device names. 

upper and lower case are not significant in pathnames: 'TESTVOL' is the same 
object as 'TestVol*. Any ASCII character is legal in a pathname. Including 
non-printing characters and blank spaces. However, use of ASCII 13, 
RETURN, In a pathname is strongly discouraged. 

2.2 TT« working Directory 

it is sometimes inconvenient to specify a complete pathname, especially when 
working with a group of files in the same volume. To alleviate this problem, 
the Operating System maintains the name of a working directory for each 
process. Vy/hen a pathname is specified without a leading "-", the name refers 
to an object in the working directory. For example, if the working directory 
is -LISA the name FORMAT.TEXT refers to the same file as 
-LISA-FORMAT.TEXT. The default working directory name is the name of the 
boot volume directory. 

You can find out what the working directory is with GET_WORKING_DIR 
You can change to a new working directory with SET_W0RKING_DIR 
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23 Ctevices 

Device names follow the same conventions as file names. Attributes like baud 
rale are conlroned by using the DEVICEjCONTROL call with the appropriate 
pathname. 

Each device has a permanently assigned priority. From highest to lowest^ the 
priorities are: 

Power on/off button 

Serial port A (RS232A) 

Serial port B (RS232B, the leftmost port) 

I/O slot 1 

I/O slot 2 

I/O slot 3 

Keyboard^ mouse^ battery-powered clock 

10 ms system timer 

CRT vertical retrace interrupt 

Parallel port 

Diskette 1 (UPPER) 

Diskette 2 (LOWER) 

Video screen 

The device driver associated with a device contains information about the 
ctevlce's ptfiyslcal characteristics such as sector size and interleave factors for 
disks. 

2.4 Storage Devices 

On storage devices such as disk drives^ the File System reads or writes file 
data in terms of pages. A pageh the same size as a block. Any access to 
data in a file ultimately translates into one or more page accesses. When a 
program requests an amount of data that does not fit evenly into some 
number of pages^ the File System reads the next highest number of whole 
pages. Similarly^ data is actually written to a file only In whole page 
increments. 

A file does not need to occupy contiguous pages. The File system keeps 
track of the locations of all the pages that make up a file. 

Each page on a storage device is self-identifying; the pagie descriptor \% stored 
with the page contents to reduce the destructive Impact of an I/O error. 

The eight components of the page descriptor are: 

Version number 

volume Identifier 

File identifier 

Amount of data on the page 

Page name 

Page position in the file 

Forward link 

Backward link 
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Each volume has a Mecffum Descriptor Data File (NODFJ^Mc/n describes the 
various attributes of the medium such as Its slze^ page lengthy block layouts 
and the size of the boot area The MDDF Is created when the volume Is 
Initialized. 

The File System also maintains a record of which pages on the medium are 
currently allocated^ and a catalog of all the flies on the volume. Each file 
contains a set of file hlnts^ which describe and point to the actual file data. 

2.5 TTie Vblume Catalog 

On a storage device^ the volume catalog provides access to the files. The 
catalog is Itself a file that maps user names Into the internal file Identifiers 
used by the Operating System. Each catalog entry contains a variety of 
Information about each file including: 

Nanoe 

Type 

Internal file number and address 

Size 

Date and time created^ last modified, and last accessed 

File identifier 

Safety switch 

The safety switch is used to avoid accidental deletions. While the safety 
switch is on, the file cannot be deleted. The other fields are described under 
the LOOKUP File System call. 

The catalog can be located anywhere on the medium. 

2.6 Labels 

An application can store its own Information about a file in an area called 
the ffle latiel The label allows an application to keep the file data separate 
from information maintained about the file. Labels can be used for any 
object in the File System. The maxlrmim label size is 128 bytes. I/O to labels 
is handled separately from file data l/a 

2.7 Logical and Physical End of File 

A file contains some number of bytes of data recorded in some number of 
physical pages. Additional pages which do not contain any file data can be 
allocated to the file. There are, therefore, two measures of the end of the 
file. The Logical End of File (LEOF) is a pointer to the last stored byte that 
has meaning to the application. The Physical End of File (PEOF) is a count of 
the number of pages allocated to the file. 

In addition, each open file has a pointer called the /7le marker\M.&\ points 
to the next byte In the file to be read or written. When the file is opened, 
the file marker points to the fint byte (byte number 0> The file marker can 
be positioned automatically or explicitly using the read and write calls. For 
example, when a program writes to a file opened with Append access, the file 
marker is automatically positioned to the end of the file before new data are 
written. The file marker cannot be positioned past LEOF except by a write 
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operation that appends data to a file; in this case the file marker is 
positioned one byte past LEOF. 

When a file is created^ an entry for it is made in the catalog specified in its 
pathname^ but no space is allocated for the file Itself. When the file is 
opened by a process, space can be allocated explicitly by the process, or 
automatically by the Operating System. If a write operation causes the file 
marker to be positioned past the LEOF marker, LEOF (and PEOF if necessary) 
are automatically extended. The new space is contigcious if possibla 

2.8 File Access 

The File System provides a device-independent bytestream interface. As far 
as an application program is concerned, a specified number of bytes is 
transferred either relative to the file marker or at a specified byte location 
in the file. The physical attributes of the device or file are not important to 
the application, except that devices that do not support positioning can 
perform only sequential operations. Programs can sometimes improve 
performance, however, by taking advantage of a device's physical 
characteristics. 

Programs can request any amount of data from a file. The actual 1/0, 
however, is performed in whole-page Increments when devices are block 
structured. Therefore, programs can optimize 1/0 to such devices by setting 
the file marker on a page boundary and m^ing I/O requests in whole-page 
increments. 

A file can be open for access by more than one process concurrently. All 
requests to write to the file are completed before any other access to the file 
is permitted. When one process writes to a file, the effect of the write 
operation is immediately available to all other processes reading the file. The 
other processes may, however, have accessed the file in an earlier state. 
Data already obtained by a program are not changed. The programmer must 
ensure that processes maintain a consistent view of a shared file. 

When you open a file, you specify the kind of access allowed on the file. 
When the file is opened, the Operating System allocates a file marker for the 
calling process and a run-time identification number called the refnum The 
process must use the refnum in subsequent calls to refer to the file. Each 
operation using the refnum affects only the file marker associated with that 
refmffn. 

Processes can share the same file marker. In global access mode, each 
process uses the same refnum for the file. When a process opens a file in 
global access mode, the refnum it gets back can be passed to any other 
process, and used by any process. Note that any number of processes can 
open a file with GlotelJRefnum, but each time the CPEN call is used a 
different refnum is produced. Each of those refnums can be passed to other 
processes, and each process using a particular refum shares the same file 
marker with other processes with the same refum. Processes using different 



2-5 



cperating System Reference Manual The File System 

refnums, however, always have different file markers, whether or not those 
refnums were obtained with Global_Refhum. 

A file can also be opened in private mode, which specifies that no other CPEN 
calls are to be allowed for that file. A file can be opened with 
Glotel_Refnum and private, which opens tr« file for global access, twt allows 
no other process to open that file. By using this call, processes can control 
which other processes have access to a file. The opening process passes the 
global refnum to any other process that is to have access, and the system 
prevents other processes from opening the file. 

Processes using global access may not be able to make any assumptions about 
the location of the file marker from one access to the next. 

2.9 Pipes 

Because the Operating System supports multiple processes, a mechanism is 
provided for interprocess connmunlcation. This mechanism is called a pipe 
Pipes are similar to the other objects In the File System — they are named 
according to the same rules, and they can have labels. 

NOTE 

Pipes will not be supported In future releases of the Operating System. 
CX) not use tr« pipe mechaiism If you want your software to be 
upward-compatible. 

As with a file, a pipe is a byte stream. With a pipe, however, information is 
queued in a first-ln-fint-out manner. Also, a pipe can have only one reader 
at a time, and once data is read from a pipe it is removed from the pipe. 

A pipe can be accessed only In sequential mode. Although only one process 
can read data from a pipe, any number of processes can write data into it. 
Because the data read from the pipe is consumed, the file marker Is always at 
zero. If the pipe is empty and no processes have it open for writing, EOF (End 
Of File) is returned to the reading process. If any process has the pipe open 
for writing, the reading process is suspended until enough data to satisfy the 
call arrives in the pipe, or until all writers close the pipe. 

When a pipe is created, its size is bytes. Unlike with ordinary files, the 
initializing program must allocate space to the pipe before trying to write 
data into it. To avoid deadlocks between the reading process and the writers, 
the Operating System does not allow a process to read or write an amomt of 
data greater than half the physical size of the pipe. For this reason, you 
should allocate to the pipe twice as much space as the lar^st amount of data 
in any planned read or write operatioa 

A pipe is actually a circular buffer with a read pointer and a write pointer. 
All writers access the pipe through the same write pointer. Whenever either 
pointer reaches the end of the pipe, it wraps back around to the first byte. If 
the read pointer catches up with the write pointer, the reading process blocks 
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until data are written or until all the writers close the pipe, similarly. If the 
write pointer catches up with the read pointer, a writing process blocks until 
the pipe reader frees up some space or until the reader closes the pipe. 
Because pipes have this structure, there are restrictions on sonne operations. 
These restrictions are discussed with the relevant File System calls. 

Processes can never make read or write requests bigger th€tfi half the size of 
the pipe because the Operating System always fully satisfies each read or 
write request before returning to the program. In other words, if a process 
asks for 100 bytes of data from a pipe, the Operating System waits until there 
are 100 bytes of data in the pipe and then completes the call. Similarly, If a 
process tries to write 100 bytes of data into a pipe, the Operating System 
waits until there is room for the full 100 bytes before writing anything into 
the pipe. If processes were allowed to make write or read requests for 
greater than half of a particular pipe, it would be possible for a reader and a 
writer to deadlock, with neither havir^ room in the pipe to satisfy its 
rec^ests. 

2.10 File System Calls 

This section describes all the Operating System calls that pertain to the File 
System. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used In the File System calls: 

Pathname = STRING[riax_Pathnarae];(» Max_Pathname = 255 «) 
E_Nanie = STRING[riax_Ename]; (* riax_EName = 32 ») 

Accesses = (Dread, Dwrlte, Append, Private, Global_Refinum); 
MSet = SET OF Accesses; 
loMode = (Absolute, Relative, Sequential); 

The Fs_Info record and its associated types are described under the LOOKUP 
call. The Dctype record Is described under the DENf^CE.CXlNTROL call. 



2-7 



CperaUng System Reference Manual We File System 

ziai MAKE_FILE and make_pipe File system calls 

flAKE_FILE (var Ecode:Integer; 
Var Path:PatnnaraB; 
LabeljSlze : Integer) 

MAKE_PIPE (var Ecxxte: Integer; 
Var Patn: Pathname; 
Label_Sl2e : Integer ) 

Ecode: Error indication 

Path: Name of new object 

LabeI_Size: Number of bytes for the object's label 

M/\KE_FILE and MAKE_PIPE create the specified type of object with the 
given name. If the pathname does not specify a directory name (more 
specifically^ if the pathname does not begin with a dash)^ the working 
directory is used. Label_Size specifies the initial size in bytes of the label. 
It must be less than or equal to 128 bytes. The label can grow to contain up 
to 128 bytes no matter what its Initial size. Any error indication is returned 
in Ecoda 

NOTE 

Pipes will not be supported in future releases of the Operating System. 
Do not use the pipe mechanism if you want your software to be 
upward-conpatible. 



The MAKE_FILE example on the next page checks to see whether the 
specified file exists before opening It. 
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CONST FileExlStS = 890; 
VAR FileRefNuBtErrorCodecINTEGER; 
FlleNafne:PathNan)e; 
Happy :BO0LEAN; 
Response: CHAR; 
BEGIN 

Happy :=FALSE; 
WHILE NOT H^)py DO 
BEGIN 

REPEAT (* get a file name *) 

•RITECFile narne: '); 
REAOLN(FlleNafne); 
UNHL LENG"m(FlleNarae)>0; 

MAKE_FlLE(ErrorCode,FileNane.O); (*no label for this file*) 
IF (ErrorCode<>0) THEN (* does file already exist? ») 

IF (ErrorCode=FileExists) THEN (* yes ») 

BEGIN 

•RITECFileName, ' already exists. Overwite? '); 
READLN(Response); 

Happy :=(Response IN ['y'^'Y']); (*go ahead and overwrite*) 
END 

aSE IPRITELNC 'Error \ErrorCode, • while creating file,') 
ELSE Happy :=TRUE; 
END; 
OPEN(ErrorCode,FileNarae,FlleRefNunt (Owrlte)); 

END; 
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2.102 KILL_C)BJECT File System Call 

iaLL_OBJECT (Var Ecode: Integer; 
Var Patti: Pathname) 

Ecode: Error indicator 

Path: Ne»ne of c*)ject to be deleted 

KILL_0BJECT deletes the object given in Path from the File System. Objects 
with the safety switch on cannot be deleted. If a file or pipe is open at the 
time of the KILL_C]BJECT call, its actual deletion is postponed until it has 
been closed by all processes that have it open. During this period no new 
processes are allowed to open it. The object to be deleted need not be open 
at the time of the KILLJDBJECT call. A KILLJDBJECT call can be reversed 
by UNKILL_FILE, as long as the object Is a file and is still open. 

The following program fragment deletes files until RETURN is pressed: 

C»NST FileN0tF0Und=894; 
VAR FileName-.PathNafne; 
ErrorCode : INTEGER; 
BEGIN 
REPEAT 

•RITECFile to delete: '); 
READLN(FileName); 
IF (FileNaraeo") THEN 
BEGIN 

KILL_OBJECT(ErrorCode, FileName); 
IF (ErrorCodeoO) THEN 
IF (ErrorCode=FileNotFound) THEN 
•RITELN(FlleName, • not found. ' ) 

ELSE iRITELN( 'Error ', ErrorCode, • while deleting file.') 
ELSE «IRITELN(FileNanie, ' deleted.'); 
END 
UNTIL (FiieNaiie="); 
END; 
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2.ia3 UNKILL_FILE File System Call 

UNKILL_FILE (Var Ecode : Integer; 
RefNum: Integer; 
Var NefnaRie:e_name) 

Ecode: Error indicator 

RefNum: Refnum of the killed and open file 

Newname: New name for the file being restored 

UNKILL_FILE reverses the effect of KILL_CIBJECT as long as the killed 
object Is a file that is still open. A new catalog entry is created for the file 
with the name given in Newname. Newname is not a full pathname: the 
resurrected file remains in the same directory. 
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2.ia4 RENAME_ENTRY File System call 

RENWC_ENTRY (Var Ecode: Integer; 
Var PathrPathname; 
Var Nevname-.EJtame) 

Ecode: Error indicator 
Path: Ojject's old name 
Newname: Object's new naiue 

RENAME_ENTRY Changes the name of an odject In the File System. 
Newname cannot De a full pathname. The name of the object Is chaiged^ but 
the object remains in the same directory. The following program fragment 
changes the file name of FORMATTER.LIST to NEWFORMAT.TEXT. 

VAR OldNaroerPathName; 

Ne«Naine:E_Nanie; 

ErrorCode: INTEGER 
BEGIN 

OldNarae : = ' -LISA-FORMATTER . LIST*; 

NenNane : = • NEWFORMAT . TEXT • ; 

RENAME_ENTRY(ErrorCode. OldNaroe. NewNaroe); 
END; 

The file's full patmame after renaming Is 

-LISA-INEWFORMAT.TEXT 

VoluTie names can be renamed by specifying only tr« volume name in Path. 
Here is a sanple program fragment which changes a volume name. Note that 
the leading dash (-), given in CfldName, is not given in NewName. 

VAR OldNamerPathName; 

NewName :E_Nanie; 

ErrorCode: INTEGER 
BEGIN 

OldName : = ' -thomas * ; 

NenName :=' steams ■ ; 

RENAhE„ENTRy (Errorcode, oldName, NewName); 
END; 
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2,ia5 LOOKUP File System call 

LOOKUP (Var Ecode: Integer; 
Var Path:PathnaiBe; 
Var Attrldirtes:Fs_lnfo) 

Ecode: Error indicator 

Path: Object to lookup 

Attributes: Information returned about path 

LOOKUP returns Information about an object in the file system. For devices 
and mounted volumes^ call LOOKUP with a pathname that names the device or 
volume without a file name component: 

DevNaroe:=' -UPPER'; (* Diskette drive 1 *) 

LOOKUP(ErrorCode^ OevName^ Inf oRec); 

If the device is currently mounted and is block structured^ all of the record 
fields of Attributes contain meaningful values; otherwise^ some values are 
undefined. 

The Fsjnfd record is defined as follows. The meanings of the information 
fields are given in Appendix E. 

FS_InfQ = RECORD 

name: ejiane; 
devnuBi: INTEGER; 
CASE OType:info_type OF 

device_t^ volumB_t: 

(iochannel: INTEGER 

devt: devtype; 

SlOt_no: INTEGER; 

fs_slze: LONGINT; 

VOl_size: LONGINT; 

blocKstructured, 

fliounted: BOOLEAN; 

operxxiunt: LONGINT; 

prlvatedev, 

remote^ 

lockeddev/: BOOLEAN; 

mountjjendlng, 

uninount_pendlng: BOOLEAN; 

volname^ 

password: ejiame; 

fsversioa 

volld, 

volnum: INTEGER; 
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blockslze, 
datasize, 
clustersize, 

filecount: INTEGER; (*Nunt)er of files on vol*) 
freecount: LONGINT; (^Nuntoer of free blocks *) 
DTVC, (* Date Volume Created *) 
D7VB, (* Date Volume last Backed up *) 
DTVS:LONGINT;(* Date Volume last scavenged *) 
riachlne_ia 
overmountstanp, 
master_copy_ld: LONGINT; 
privileged, 

•rltej)rotected: BOXEAN; 
master, 
copy, 

scavenge_flag: BOOLEAN); 
oDject_t: ( 

size: LONGINT; (*actual no of bytes written *) 
psize: LONGINT; (^physical size in bytes *) 
Ipsize: INTEGER; (*Logical page size in bytes *) 
filetype; 



entrytype; 



ftype: 

etype: 

DTC, 

DTA, 

DTtt 

DTB: 

refnura: 

fmark: 

acmode: 

nreaders, 

nwriters, 

nusers: 

fuld: 

eof, 

safety_oa 

kswitch: BOOLEAN; 

private, ( 
locked, ( 



LONGINT; 
INTEGER; 
LONGINT; 
roset; 

( 

( 
INTEGER; 
Uid; 



(* Date Created 
(* Date last Accessed 
(* Date last Modified 
(* Date last Backed up 



(* file marker *) 
(* access mode *) 
Number of readers *) 
Number of writers *) 

(* Nuntoer of users «) 
(* unique identifier *) 
(* EOF encountered? *) 
(* safety switch setting 
(» has file been killed? 
File opened for private access? 
Is file locked? *) 



END; 



protected : BOOLEAN); (* File copy protected? *) 
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Uld = INTEGER; 

Info_Type = (devlce_t^ volume_t, obJect_t); 

Devtype = (dlskdev, pascalML seqdev, bltbkt. non_lo); 

Flletype «= (undefined^ MDOFFile, rootcat^ freelist^ 

badblocks. sysdatsL spooL exec, usercat^ pipe, 

txx)tf lie, svapdatcu svapcode, ramap, userflle, 

killedobject); 
Entrytype - (enptyentry, catentry, llnkentry, flleentry, 

plpeentry, ecentry, kllledentry); 

Tne eof field of the Fs_infO record is set after an attempt to read more 
bytes than are availgyDle from the file marker to the logical end of the file, or 
after an attempt to write when no disk space is availahle. If the file marker 
Is at the twentieth byte of a twenty- five byte file, for example, you can 
read up to 5 bytes without setting eof, but if you try to read 6 bytes, the 
File System gives you only 5 bytes of data and eof is set 

The following program reports how mcny bytes of data a given file has: 

VAR lnfoRec:Fs_Info; ("Information returned by LOOKUP and INFO«) 
FlleNaine:PathNane; 
ErrorCode: INTEGER; 
BEGIN 
•RITECFlle: '); 
REAOLN<FlleNaine); 

LOOKUPCErrorCode, FlleNanie, inf oRec); 
IF (Errorcode<>0) THEN 
IIRITELN( 'Cannot lookup ',FlleNaine) 

ELSE 

KRlTELNCFlleName, ' has ', Inf oRec. Size, ' bytes of data.*); 

END; 
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Ziae nsFO File system Call 

INFO (Var Ecode: Integer; 
RefNum: Integer; 
Var Reflnfo:Fs_Info) 

Ecode: Error indicator 

RefNuffl: Reference number of object In File System 

Refinfo: Information returned about RefNum's object 

INFO serves a function similar to tbat of LOOKUP but is applicable only to 
objects in the File System that are open. The definition of the FsjnfO 
record is given under LOOKUP and in Appendix A, 
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2.10.7 SET_FILE_INFO File System call 

SET_FILE_IhFO ( Var Ecocte: Integer; 
RefNum: Integer; 
Fsl:Fs_Info) 

Ecode: Error indicator 

RefNum: Reference number of object in File System 

Fsl: New Information about tne object 

SET_FILE_nsFO Changes the status information associated with a given object. 
This call works In exactly the opposite way that LOOKUP and INFO work, in 
that the status information is given by your program to SET_FILE_IhFa The 
Fsl argument is the same type of Information record as that returned by 
LOOKUP and INFQ The object must be open at the time this call is made. 

The following fields of the information report may be changed: 

fiie_scavenged 
file_ciosed by_os 
file_left_open 
user_type 
user_sut)type 
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2.108 CFEN File System Call 

OPEN (Var Ecode: Integer; 
Var PathrPathnaroe; 
var RefNum: Integer; 

Hanlp.-nset) 

Ecode: Error Indicator 

Path: Narne of object to be opened 

RefNum: Reference number for object 

Manip: Set of access types 

The OPEN call opens an object so that it can be read or written to. When 
you call OPEN, you specify the set of accesses that will be allowed on that 
file or sequential device. The available access types are: 

• Dread — Allows you to read the file 

• D«rite — Allows you to write in the file (to replace existing 
data) 

• /^jpend — Allows you to add on to the end of the file 

• Private — Prevents other processes from opening the file 

• Global_Refnum — creates a refnum that can be passed to other 
processes 

Note that you can give any number of these modes simultaneously. If you 
specify Dwrite and Append in the same OPEN call, Dwrite access will be used. 
See Section 2.8 for more Information on Global_Refnum and Private access 
modes. 

If the object opened already exists and the process calls WRITE_DATA 
without having specified /Nppend access, the object can be overwritten. The 
Operating System does not create a temporary file and wait for the 
CL0SE_OBJECT call before deciding what to do with the old file. 

An object can be opened by two separate processes (or more than once by a 
single process) simultaneously. If the processes write to the file without using 
a global refnun, they must coordinate their file accesses so as to avoid 
overwriting each other's data 

Pipes cannot be opened for Dwrite access. You must use /^ppend if you want 
to write into the pipe. To set up a private pipe, the reader process opens the 
pipe first, specifying Dread mode; the writer process then opens the pipe with 
Append Private access mode. 
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2.10.9 CLOSE_OBJECT File System call 

CLOSE_OBJECT (Var Ecode : Integer; 
RefNuni: Integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be closed 

If RefhJum is not global^ CLOSE_CBJECT terminates any use of RefNum for I/O 
operations. A FLUSH operation Is performed automatically and the file Is 
saved In Its current state. If RefNum Is a global refnum and other processes 
have the file open, RefNum remains valid for these processes and other 
processes can still access the file using RefNum 

The following program fragment opens a file, reads 512 bytes from It, and 
then closes the file. 

TYPE Byte=-128..127; 
VAR FlleNaroerPatriNaffle; 

ErrorCode, FlleRefNum: Integer; 
ActualBytes :Longlnt; 
Buffer:ARRAY[0..511] OF Byte; 
BEGIN 
OPEN(ErrorCode, FlleName, FlleRefNum, [DRead] ); 
IF (ErrorCode>0) THEN 

•RITCLN( 'Cannot open '^FlleNarae) 
aSE 
BEGIN 
READ_DATA(ErrorCode, 
FlleRefNum, 
0RD4(aBuffer), 
512, 

ActualBytes, 
Sequential, 
0); 
IF (ActualBytes<512) THEN 

•RITECOnly read *, ActualBytes, ' bytes from ',FileName); 
CLOSE_oeJECT(ErrorCode, FlleRefNum); 
END; 
END; 
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ziaio READ_DATA and WRITE.DATA File System calls 

READJJATA (Var Ecode: Integer; 
RefNum: Integer; 
Oata_Addr :LongInt; 
Oount-.LongInt; 
Var Actual rLongInt; 
r(ode:loncxle; 
Offset iLonglnt); 

•RITEJJATA (Var Ecode: Integer; 
RefNum: Integer; 
Data_Addr :Longlnt; 
Count :LongInt; 
var Actual :Longlnt; 
node:Iohode; 
Offset :LongInt); 

Ecode: Error indicator 

RefNum: Reference number of object for I/O 

Data_Addr: Address of data (source or destination) 

Count: Number of bytes of data to be transferred 

Actual: Actual number of bytes transferred 

Mode: I/O mode 

Offset: Offset (absolute or relative modes) 

READ_DATA reads Information from tne device^ pipe, or file specified by 
RefNum, and WRITE_DATA writes information to it. Data_Addr is tne 
address for tne destination or source of Count bytes of data. Tne actual 
number of bytes transferred is returned In Actual. 

Mode can be absolute, relative, or sequential, in absolute mode. Offset 
specifies an absolute byte of tne file, in relative mode. Offset specifies a 
byte relative to tne file marker, in sequential mode. Offset is ignored 
(assumed to be zero); transfers occur relative to tne file marker. Sequential 
mode (wnicn is a special case of relative mode) is the only access mode 
allowed for reading or writing data in pipes or sequential (non-disk) devices. 
Non-sequential modes are valid only on devices that support positioning. The 
first byte is nunnbered 0. 

If a process attempts to write data past the Physical End of File on a disk 
file, the Operating System automatically allocates enough additional space to 
contain the data. This new space, may not be contiguous with the previojs 
blocks. You can use the ALLOCATE call to ensure that any newly allocated 
blocks are located next to each other, although they may not be located near 
the rest of the file. 

READ_DATA from a pipe that does not contain enough data to satisfy Count 
suspends the calling process until the data arrives in the pipe. If there are no 
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writers, the end-of-flle Indication (error 848) Is returned In Ecode. Because 
pipes are circular, WRITE_DATA to a pipe with Insufficient room suspends the 
calling process (the writer) until enough space Is available (until the reader 
has consumed enough data). If no process has the pipe open for reading and 
there Is not enough space In the pipe, the end-of-flle indication (848) Is 
returned In Ecode. 

?MOTE 

READ_DATA from the MAINCONSOLE or ALTCONSOLE devices must 
specify Count - 1. 

The following program copies a file. Note that you must supply the correct 
location for Syscall in the second line of the program. 

PROGRAM CopyFile; 

USES (*Syscall.ObJ*) SysCall; 

TYPE By te=-128..127; 

VAR oldFiicNeiflle-.PatnNaine; 

OldRef Nunt NewRefNuin: INTEGER; 

BytesRead, BytesVr Itten :LONGINT; 

ErrorCode: INTEGER; 

Response :CHAR; 

BufferrARRAY [0..511] OF Byte; 
BEGIN 
•RITECFlle to copy: '); 
READLN(OldFlle); 

0PEN(ErrorCode,01dFile,01dRefNuiit [DRead]); 
IF (Errorcode>0) THEN 
BEGIN 

IfRITELNCError *, ErrorCode, ' while opening •,01dFile); 

EXIT(CopyFile); 
END; 

WRITECNew file name: '); 
REAOLN(NevFile); 
MAKE FILE(ErrorCode,NeiFile,0); 
OPEN^ErrorCode, MenFile, MeKRefNunt [DWite]); 
REPEAT 

READ_DATA( ErrorCocte, 
OldRefNunt 
0RD4(aBirffer), 

312^ BytesRead, Sequential, 0); 
IF (ErrorCode=0) AND (BytesRead>0) THEN 
•RITEJJATA (ErrorCode, 
NenRefNum, 
0RD4(aBuffer), 

BytesRead, Bytesiritten, Sequential, 0); 
UNTIL (BytesRead=0) OR (ByteslPritten=0) OR (ErrorCode>0); 
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IF (Errorcocte>o) then 

WRITELNCFlle copy encountered error '^ErrorCode); 
CLOSE_OBJECT(ErrorCode,NeiiRefNuro); 
a0SE_0BJECT(ErrorCo(le,01dRefNuHi); 
END. 
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2.10.11 RE/oj_ABEL and WRITE JLABEL File System calls 

READ_LABEL (Var Ecode: Integer; 
Var Patn:Patnname; 

DatajWdr :Longint; 

count rLongInt; 
Var Actual :Longlnt) 

iRITEJLABEL (Var Ecode: Integer; 
Var Path .-Pathname; 

Oata_Addr : Longint; 

Count rLongInt; 
Var Actual :LGnglnt) 

Ecode: Error Indicator 

Path: Name of object containing the label 

Data_Addr: source or destination of I/O 

Count: Number of bytes to transfer 

Actual: Actual number of bytes transferred 

These calls read or write the label of an object in the File System. I/O 
always starts at the beginning of the label. Count is the number of bytes the 
process wants transferred to or from Data_/\ddr, and /\ctual is the actual 
HLffTTber of bytes transferred. An error is returned if you attempt to read 
more than the maximum label slze^ 128 bytes. 
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2.30.12 DEVICE_CONTROL File System Call 

DEVICZaXiTROL (Var Ecode: Integer; 
Var Path:Pathnflne; 
Var CPani:Dctype) 

Ecode: Error indicator 

Path: Device to be controlled 

CParra: ft record of information for the device driver 

DEVICE_CONTRCX. is used to send device-specific information to a device 
driver or to obtain device-specific information from a device driver. 

Regardless of whether you are setting device-control paiameters or 
requesting information^ you always use a record of type Dctype. The 
structure of Dctype iS: 

Dctype » REEQRD 

dcVersion: INTEIGER; 

decode: INTEGER; 

dcData: ARRAY [0. .9] Of LQNGINT 

END;. 

dcVersion: currently 2 

decode: control code for device driver 

dcData: specific control or data parameters 

2.10.12.1 Setting Device-Control Infarmafcion 

Before you use a device, you call DEVICE__CONTROL to set the device 
driver. Once you begin using the device, you call C^VICE_CO^JTROL as 
necessary. 

Table 2-1 shosvs which groups of device-control functions must be set before 
using each type of device. Table 2-2 shows which characteristics are 
contained in each ^oup. For example, you must set Group A for RS-232 
input. As you see in Table 2-2, Group A indicates the type of parity used 
with the device. Each group requires a separate call to DEVICE_CCMSlTROL, 
and you can set only one characteristic from each group. If you set more 
than one from the same group for a particular device, the last one set will 
apply. 
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Table 2-1 

DEVICE_CONTROL Functions Required 

before Using a Device 



Device Tvoe 


Device Name Reauired Grouos 


Serial RS232 for 


RS232A or RS232B 


ft,C.D,E, 


input 




F, G, L, M, N 


Serial RS232 for 


RS232ft or RS232B 


aB,c,a 


output or printer 




H, I,M,N 


Profile 


SLOTxCHfiNy (where 
X and y are numbers) 
or PflRflPORT 


3 


Parallel printer 


SLOTxCHfiNy (where 
X and y are ntmbers) 
or PflRflPORT 


I 


Console screen and 


MfllNCONSOLE or 


I 


keyboard 


ALTCONSOLE 




Diskette drive 


UHHhR or LCMER 


3 



Here is a sample program that shows how a device-control parameter is set. 
This program sets the parity attribute for the RS232B port to "no parity." 
Note that the parity attribute requires only that you set cparm.dccocle and 
q;M9rm.dcdai;8[0]. Other parameters require that you also set cparm.dcdaia[l] 
and cparni.dcdata[2]. They are set in a similar manner. 

VflR 

cpaoTR: dcty(»; 
exrnum: integer; 
path: pathnane; 

BEGIN 

path:='-flS232B'; 

c|Mani.dcversion:==2; (* always set this value *) 

cpam.dcccKte:= 1; 

cpaiii . dcdata[0] .- = 0; 

DEVICE_caNTRDL( exxntn, path, cpaim); 

EN); 
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Table 2-2 shows how to set cparm.dccode^ crrarm.dcdatfl[Ol cpBriTLdcdatfl[lI 
and cparni.ck:datfi[2] for the various awaileible attributes. Note that any 
values in c|»rm.ctedata past cpflrni.dccteta[2] are ignored when you are setting 
attributes documented here. 



Table 2-2 
DEVICE.CONTROL Output Functional Groups 



nJCTION 



-decode .dcdetefOl .dcdataTl] .dcdataf2l 



GrcMjp ft Perity.- 
No parity, 8 bits 

of data 
Odd parity, 7 bits 

of data 
Even parity, 7 bits 

of data 
8 bits of data plus 

ninth bit odd parity 
No parity, input 

stripped to 7 bits 

Groi^ B, Output Handshake 
None 1 

DTR handshake 2 
>«]N/KOFF handshake 3 
delay after CR, LF 4 

Groi^y C?-, Baud rate.- 



ms delay 



baud 



Grot^i D, Input waiting during Read-Data: 
wait for Count bytes 6 
return whatever rec'd 6 1 

Group E?, Input handshake: 
no handshake 7 

9 -1 
DTR handshake 7 
)ON/X0FF handshake 8 

Grmxp JP, Input typeahead buffer: 
flush only 9 -1 

flush and resize 9 bytes 
flush, resize, 
and set threshold 9 bytes 



-1 



-2 
-2 

lew 



32767 



-2 
-2 



hi 
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Table 2-2 (continued) 

FUCTION .decode .dcdataTOl .dcdfltrfn ■dcdatar2l 

Garoup G, Disconnect Detection: 

none 10 — 

BREfK detected 
means disconnect 10 nonzero 

Grouf> H, Timeout on output (handshake interval): 
no timeout 12 

timeout enabled 12 seconds 

Group I, Automatic linefeed insertion: 
disabled 17 

enabled 17 1 

Group J*, Disk errors (set to 1 to enable, to to disable): 
enable sparing 21 sparing rewrite reread 

Grouft K?, Break command (never required, available only on serial 

RS232 devices): 
send break 13 millisecond 

duration 
send break 13 millisecond 1 

while lowering DTR duration 

Group U Timeout on Input: 

No timeout 14 

Timeout enabled 14 seconds — — 

Group M, K^ffl< during Close_Object: 
enabled (default) 25 nonzero 
disabled 25 

Group \^, Set Modem Timeouts (Int'l MODEM A driver only): 
Set timeouts 22 recovery carrier connect 

Groufi P, Wait until modan connects (Int'l fttX^M A driver only) 
Wait 24 — — 

(returns with 
errnL»iiJ=645 
if no connect) 



2-27 



Opm'ating S^-sism Reference Manual The File S^'Stem 



l.-Using C^oup C, you can set baud to any standard rate. However^ 3600, 
7200, and 19200 baud are available only on the RS232B port. 

2. In Group E, to specify no input handshake, first make the call with the 
device control code 7, then call again with the device control code 9, as 
shown. 

3. Low and Hi under Qroup F set the low and high threshold in the typeahead 
input buffer. When Hi or more bytes are in the input buffer, XOFF is sent 
or DTR is dropped. When Low or fewer bytes remain in the typeahead 
buffer, XON is sent or DTR is reasserted. The size of the typeahead buffer 
(bytes) can be any value between and 1024 bytes inclusive. 

4. In Ck'oup J, enabling disk sparing lets the device driver to relocate blocks 
of data from areas of the disk that are found to be bad. Enabling disk 
rewrite allows the Operating System to rewrite data that it had trouble 
reading, but finally managed to read. This condition is referred to as a soft 
error. Enabling disk reread tells the Operating System to read data after 
they are written to make certain that they were written correctly. 

5. When sending a break command, as shown in G^oup K, any device control 
from Group A removes the break condition even if the allotted time has not 
yet elapsed. Also, sending a break will disrupt transmission of any other 
character still being sent. If you want to make certain that enough time has 
elapsed for the last character to be transmitted, call VflRITEJDATA with a 
single null character (equal to 0) just prior to calling DEVICE_CCMslTROL to 
send the break. 

6. In C^oup N, recoK-'ery is the minimum number of milliseconds required by 
the modem between calls. Carrier is the number of milliseconds without 
cairier detect, before the driver disconnects from the line. Connect is the 
maximum number of seconds the driver will wait when Qroup P 
Device_Control is subsequently issued. 
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TaJDle 2-3 gives a list of mnemonic constants that you can use in place of 
explicit numbers when setting [>xode. These mnemonics are provided in the 
SysCall unit for convenience. 





Table 2- 


3 






Dccode Mnemonics 




Decode 


Mnemonic 


Decode 


Mnemonic 


1 


dvParity 


14 


no mnemonic 


2 


dvOutDTR 


15 


dvErrStat 


3 


dvOutXON 


16 


dvGetEvent 


A 


dvOutDelay 


17 


dvftutoLF 


5 


dvBaud 


18 


no mnemonic 


6 


dvInWait 


19 


no mnemonic 


7 


dvInDTR 


20 


dvDiskStat 


8 


dvInXON 


21 


dvDiskSpare 


9 


dvTypeahd 


22 


no mnemonic 


10 


dvDiscon 


23 


no mnemonic 


11 


dvOutNoHS 


24 


no mnemonic 


12 


no mnemonic 


25 


no mnemonic 


13 


no mnemonic 







2.10.12.2 Obtaining Device-Control Informeltion 

To use DEVXCEjCONTITOL to find out about the current state of a particular 
device, simply give the pathname for the particular device along with a 
function code for the type of information you need. The record of type 
Dctype that you supply is returned filled with information. 

There are three types of information requests you can make. Note that each 
type applies only to some of the available devices. The request types and 
the returned information are described in Table 2-4. 

Table 2-5 shows the error code provided in response to a Dccode=15 
information request. This code is given in cparm.dcdata[0]. The code, a long 
integer, is shown in Table 2-5; the bits and bytes are numbered from the 
right, counting from 0. The meaning assigned to the bit applies if the bit is 
set (equals 1). 

Here is a program fragment that uses DEVICE_CONTROL to get information 
about the lower diskette drive. 

VflR 

cpam: dctype; 

ezrntii: INTEGER; 

path: pat^ffwane; 
BEGIN 

path:='-U]MER'; 

cpani.dcveTsion:=2; (* always set this value *) 
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cpapni.dccc^ := 20; 
DEVICEJIONTRDLCexTnuni, path, cpami); 
WITH cpaiim iX3 

HRITELN (dcdata[0], dcdata[lL iic(iata[2L dcdata[3L 
dcdata[4L dcdatahL dcdata[6] ) 



EhD; 



Table 2-4 
Device InT ormeition 



Decode Devices 



Returned in Dcdata 



15 ProFiles 



16 Console Screen 
and Keyboard 



[0] contains disk error status on last 
hardware error (see Table 2-5) 
[1] contains error retry count 
since last system boot 

[0] contains numbers 0-10, 
which indicate events: 

= no event 

1 = upper diskette inserted 

2 = upper diskette button 

3 = lower diskette inserted 

4 = lower diskette button 

6 = mouse button down 

7 = mouse plugged in 

8 = power button 

9 = mouse button up 
10 = mouse unplugged 

[1] contains the current state of certain 
keys, indicated by set bits (if the bit is 
1, the key is pressed) (bits are numbered 
from the right) 

= caps lock key 

1 = shift key 

2 = option key 

3 = command key 

4 = mouse button 

5 = auto repeat 

[2] contains X and Y coordinates of mouse, 
X in left 2 bytes, Y in right 2 bytes 
[3] contains timer value in milliseconds 
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DccaMte Devices 



Table 2-4 (continued) 
Returned in Pcdata 



18 



RS232^ Modem A Read and clear input error counters 
[01 contains count of framing errors 
[1] contains count of parity errors 
[2] contains count of overrun errors 
[3] is count of buffer overflow errors 



19 



RS232, Modem ft 



[O] returns last value passed in 
Group ft, Dcdata[0] 

[1] returns last value passed in decode 
for Group B^ or negative value of 'ms 
delay' if 'delay after CR, LF' was selected 
[2] returns baud rate 
[3] upper 16 bits: returns last value 
from dcdata[0]^ Group D 
lower 16 bits: returns last value 
from dccocte, Group E 
[4] returns value from 'bytes' Group F 
[5] upper 16 bits: value from 'low'. 
Group F 
lower 16 bits: value from 'hi'. 
Group F 
[6] returns 'seconds' from group H 
[7] upper 16 bits: value from 
dcdata[l] Group G 

lower 16 bits: value fron 
dcdata[0] Group I 
[81 returns value from dcdata[OL 
Group L 

[91 returns number of characters waiting 
in driver's input buffer 



2-31 



Operating S^-stem Reference Manuel 



The File S^'Stem 



Table 2-4 (contint^d) 
IXxode Devices Returned in Pcdata 



20 



F>roFile or 
Diskette Drive 



23 



Modem ft 



[0] contains: 

= no disk present 

1 = disk present (but not 

accessed yet) 
The following indicate that a disk is 
present and has been accessed at 
least once. 

2 = bad block track appears 

unformatted 

3 = disk formatted by some 

program other than the 
Operating System 

4 = OS-formatted disk 
[1] contains: 

= no button press pending 

1 = button press pending, 

disk not yet ejected 
[2] contains nimiber of available spare 
blocks, 0-16, meaningful only when 
Dcdata[0] = A and for a diskette 
[3] contains: 

= both copies of the bad-block 

directory OK 

1 = one copy is corrupt 

(meaningful only when 
Dcdata[0] « 4) 
[4] contains: 

= sparing disabled 

1 = sparing enabled 
[5] contains: 

= rewrite disabled 

1 = rewrite enabled 
[6] contains: 

= reread disabled 

1 = reread enabled 

[0] returns 'recovery'. Group N 
[1] returns 'carrier'. Group N 
[2] returns 'connect'. Group N 
[3] returns: 

= not connected 

1 = connected 
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Table 2-5 
Disk Hard-Error Codes 

Byte 3 
7 = ProFile received <> 55 to its last response 

6 = Write or write/verify aborted because more than 532 bytes of 

data were sent or because ProFile could not read its spare 
table 

5 = Host's data is no longer in RftM because ProFile updated its 

spare table 

4 = SEEK EPROR — unable in 3 tries to read 3 consecutive headers 

on a track 

3 = CRC error (only set during actual read or verify of 

write/verify, not while trying to read headers after seeking) 

2 = TI^€OUT ERROR (could not find header in 9 revolutions) — not 

set while trying to read headers after seeking 

1 « Not used 

= Operation unsuccessful 

Byte 2 

7 = SEEK ERFO? ~ unable in 1 try to read 3 consecutive headers on 

a track 

6 a Spared sector table overflow (more than 32 sectors spared) 

5 = Not used 

4 = Bad block table overflow (more than 100 bad blocks in table) 

3 = ProFile unable to read its status sector 

2 = Sparing occurred 

1 = Seek to wrong track occurred 

= Not used 

Byte 1 

7 = ProFile has been reset 

6 = Invalid block number 

5 = Not used 

4 = Not used 

3 = Not used 

2 = Not used 

1 = Not used 
= Not used 

Byte 
This byte contains the number of errors encountered when rereading a 
block after any read error. 
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2.iai3 ALLOCATE FUe system call 

ALLOCATE (Var Ecode: Integer; 
RefNuM: Integer; 
Contiguous :Boolearv 
Count :Longlnt; 
Var Actual: Integer) 

Ecode: Error indicator 

RefNum: Reference nuntoer of object to de allocated space 

Contiguous: True = allocate contiguously 

Count: Number of blocks to be allocated 

Actual: Nunt)er of blocks actually allocated 

Use /M_LOCATE to Increase the space allocated to an object If possible^ 
ALLOCATE adds the requested number of blocks to the space available to the 
object referenced by RefNum. The actual number of blocks allocated Is 
returned In Actual If Contiguous is true^ the new space is allocated in a 
single^ unfragmented space on the disk. This space is not necessarily adjacent 
to any existing file blocks. 

ALLOCATE applies only to objects on block-structured devices. An attempt to 
allocate more space to a pipe is successful only if the pipe's read pointer is 
less than or equal to its write pointer. If the write pointer has wrapped 
around but the read pointer has not an allocation would cause the reader to 
read invalid and uninitialized data, so the File System returns error 1186 in 
this case. 
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2.iai4 COMPACT File System call 

COMPACT (var Ecode.-lnteger; 
RefNum:Integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be conpacted 

COMP/VCT changes the Physical End of File to deallocate any blocks after the 
block that contains the Logical End of File for the file referenced by RefNum. 
(See Figure 2-1.) COMPACT applies only to objects on block-structured 
devices. As In the case of ALLOCATE^ compaction of a pipe Is legal only If 
the read pointer Is less than or equal to the write pointer. If the write pointer 
has wrapped around, but the read pointer has not, compaction could destroy 
data In the pipe. The File System returns error 1188 In this case. 
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2.iai5 TRUNCATE File system call 

TRUNCATE (Var Ecode: Integer; 
RefNurarlnteger) 

Ecode: Error indicator 

RefNum: Reference number of object to be truncated 

TRUNCATE sets the Logical End of File indicator to the current position of 
the file marker. Any data beyond the file marker are lost, TRUNCATE 
applies only to block-structured devices. Truncation of a pipe can destroy 
data that have been written but not yet read. As the diagram shows, 
TRUNCATE Changes only LEOF, COMPACT, on the other hand, changes only 
PEOF. 



r 



TRUNCATE - 



new 
LEOF 




-«pr-~4 



r 



COMPACT n 



new 
PEOF 



ALLOC ;ated 



File Marker 



old 
LEOF 



Old 
PEOF 



Figure 2-2 
The RelaUonshlp of COMPACT and TRUNCATE 

In this figure the boxes represent blocks of data Note that LEOF can point to 
any byte in the file but PEOF always points to a block boundary. Therefore, 
TRUNCATE can reset LEOF to any byte in the file, but COMPACT can reset 
PEOF only to a block boundary. 
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2.iai6 FLUSH File system Cdll 

FLUSH (Var Ecode:lnteger; 
RefNuRi:Integer) 

Ecode: Error indicator 

RefNum: Reference number of destination of I/O 

FLUSH forces all buffered Information destined for the object identified by 
RefNum to be written out to that object 

A side effect of FLUSH Is that all FS buffers and data structures are flushed 
(as well as the control information for the referenced file), if RefNum is -l^ 
only the global File System Is flushed. This Is a method by which an 
application can ensure that the File System is consistent 
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ziai7 SET.SAFETY FUe system cai 

SET SAFETY (Var Ecode: Integer; 
Var Patn:PattYiaMe; 
Onoff:Boolean) 

Ecode: Error indicator 

Path: Name of object containing safety switch 

On_Off : Set safety switch: 

On » true 

Off » false 



Each object in the File System has a "safety switch" to help prevent accidental 
deletloa If the safety switch is on, the object cannot be deletea 
SET_s/^FETY tums the switch on or off for the object identified by path. 
Processes that are sharing an object should cooperate with each other when 
setting or clearing the safety switch. 
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2.10.18 SET_WORKING_DIR and GET_WC]RKINQ_DIR File System Calls 

SET_I«RKING_DIR (Var Ecode: Integer; 
Var Path:Patnname) 

GET_lWRiaNG_OIR (Var Ecode: Integer; 
Var Path:PatrYianie) 

Ecode: Error Indicator 
Path: Working directory name 

The operating System uses the working directory name to resolve partially 
specified pathnames Into complete pathnames. GET_WORKING_DIR returns the 
current working directory name In Patn. SET_WORKING_DIR sets the working 
directory name. 

The following program fragment reports the current name of the working 
directory md allows you to set It to something else: 

VAR iorklngPlrrPathNaroe; 

ErrorCode : INTEGER; 
BEGIN 

GET_l«RiaNG_DIR(ErrorCode, ItorkingDlr); 

IF (Errorcode<>0) THEN 
•RITELNC 'Cannot get the current working directory!') 

ELSE «RITELN('TTie current working directory is: '^iorkingDir); 

l»RITE('Ne« mrking directory name: *); 

READLN(»orkingDir); 

SET_WRiaNG_oiR(ErrorCode, itorkingDir); 

END; 
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Z10.19 RESET_CATALOG, RESET_SUBTREE, GET_NEXT_ENTRY, and 
LOOKUP_NEXT_ENTRY File System Calls 

RESET_CftTftLOG (var ecode : integer; 
var path : pathname) 

RESET_SUBTREE (var ecode : integer; 
var path = pathname) 

GET_NEXT_ENTRY (var ecode r integer; 
var prefix z e_name; 
var entry = e_name) 

LOOKUP_NEXT_ENTRY (var ecode = integer; 
var prefix : e_nane; 
var InfoRec : O_lnfo) 

ecode-. Error indicator 

path: Name of the directory to be scanned 
prefix: Find names beginning with this substring 
entry: Name of the next object (with matching 
prefix) in the directory 

These procedures are used to enumerate the objects contained in a 
directory. RESET_CATALCX3 instructs the file system that the directory 
named in path is to be scanned. GET_NEXT_ENTRY returns the name of the 
next object in the directory. Only names beginning with the substring prefix 
will be found. If prefix is the null string, then all names in the directory 
will be found. If there are no more objects in the directory, an end-of-file 
error (848) is returned. RESET_SUBTREE is equivalent to RESET_CATALOG, 
but indicates that the subtree rooted at the directory named in path is to be 
scanned. Subsequent calls to GET_NEXT_ENTRY will return names from the 
subtree according to a pre-order traversal. L(X)KUP_NEXTJENTRY 
combines the actions of GET_KEXT_EI4TRY and QUICK_LOOKUP into one 
operation, and is considerably more efficient than those two procedures 
called serially. When traversing a subtree by calling LOOKlP_MEXT_ENTRY, 
the Iei''eJ field of the QJlnfo record indicates the les/el of the object within 
the directory hierarchy. Objects in the root directory of a disk volume ere 
at level zero. 
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2.1020 MOUNT ana urjMOUNT FUe System caus 

HOUNT (var Ecode:lnteger; 
var VNaHie:E_Nane; 
var Pass«ord:E_Naiie 
Var DevnaRie:C_NaRie) 

UNMOUKT (Var Ecode.-Integer; 
Var VnaiiB:E_naiie) 

Ecode: Error indicator 

vname: Volume name 

Password: Password for device (currently ignored) 

Devname: Device name 

MOUNT and UNMOUNT handle access to sequential devices or block-structured 
devices. For block-structured devices^ MOUNT logically attaches the volume's 
catalog to the File System. The name of the volume mounted is returned In 
the ^lame parameter. 

UNMOUNT detaches the specified volume from the File System, No object on 
that volume can be opened after UNMOUNT has been called. The volume 
cannot be unrmounted until all the objects on the volume have been closed by 
all processes using them. 

Devname is the name of the device on which a volume is being mounted. 
Devname should be given without a leading dash (-). 

vname is the name of the volume that was successfully mounted, and is 
returned. 
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Processes 



A process is an entity in the Lisa system that performs work. When you ask 
the Operating System to run a program^ the OS creates a specific instance of 
the program and its associated data. That instance is a process. 

The Lisa can have a number of processes at any one time; they appear to be 
running simultaneously. Although processes can share code and data, each 
process has its own stack. 

Only one process at a time can use the CPU. The Scheduler determines 
which process is active at a particular time. The Scheduler allows each 
process to run until some condition that would slow execution occurs (an I/O 
request, for example). At that time, the running process is saved in its 
current state. The Scheduler then checks the pool of ready-to-run processes. 
When the original process later resumes execution, it picks up where it left 
off. 

The process scheduling state has three posslDlllties. A ivmlng process is 
actually executing instructions. A ready process is ready to execute but is 
being held back by the Scheduler. A Mocked process is ignored \i)i the 
Scheduler. It cannot continue its execution until something causes it to 
become ready. Processes commonly become blocked while awaiting 
completion of I/O, although there are a number of other likely causes. 
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3wl Process Stnjcture 

A process can use up to 16 data segments and 106 code segments. 

The layout of the process address space for user processes is shown in Figure 
3-1. 

Seg# 



I Unavailable 



106 

+ — 

107 



122 
123 



124 



125 

♦ — 

126 



127 



User Code Segnents 



LDSN 1 

(data segments) 

LDSN 16 

Stack 

Shared Intrinsic Unit Data 

Screen 

Reserved 

Reserved 



Figure 3-1 
Process Address Space Layout 

Each process has an associated priority^ an integer between 1 and 255. The 
Scheduler usually executes the highest-priority ready process. The higher 
priorities (226 to 255) are reserved for the Operating System. 

32 Process Hierarchy 

When the system is first started^ several system processes exist At the base 
of the process hierarchy, shown in Figure 3-2, is the root process, which 
handles various internal Operating System functions. It has at least two sons: 
the Memory Manager process and the shell process. 

The Memory Manager process handles code and data segment swapping. 
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The snen process is a user process thai is automatically started when the OS 
Is initialized. It Is typically a command Interpreter^ but It can be any 
program. The OS simply looks for the program called SYSTEM.SHELL and 
executes it 



Root Process 




Memory Manager 

Process 

User 

Process 



Other User Processes 



Other 



Figure 3-2 
Process Tree 

Any other system process (the network control process, for example) Is a son 
of the root process. 

3.3 Process Creation 

When a process is created, it is placed in the ready state with a priority equal 
to that of the process that created it. All the processes created by a given 
process can be thought of as existing in a subtree. Many of the process 
management calls affect the entire subtree of a process as well as the process 
Itself. 

3.4 Process Control 

Three system calls are provided for explicit control of a process. These calls 
allow a process to kill, suspend (block), or activate any other user process in 
the system, as long as the process identifier is known. Process-handling calls 
are not allowed to control Operating System processes. 

3.5 Process Scheduling 

Process scheduling is based on the priority established for the process and on 
requests for Operating System services. 

The Scheduler generally executes the highest-priority ready process. Once a 
process is executing, it loses the CPU only under certain circumstances. The 
CPU Is lost when there is some specific request for the process to wait (for 
an event, for example), when there is an 1/0 request, or when there is a 
reference to a code segment that is not in memory. A process that makes 
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any Operating System call may lose the CPU. The process gets the CPU Pack 
when the Operating System is finished^ except under the following conditions: 

• The running process requests input or output. The Scheduler starts the 
next highest-priority process running while the first process waits for the 
1/0 to complete. 

• The running process lowers Its priority below that of another ready process 
or sets another process's priority higher than its own. 

• The running process explicitly yields the CPU to another process. 

• The running process activates a higher-priority process. 

• The running process suspends itself. 

• A higher-priority process becomes ready. 

• The running process needs code to be swapped into memory. 

• The running process executes an event-wait call. 

• The running process calls DELAY_TIME. 

Because the Operating System cannot seize the CPU from an executing 
process except In the cases noted above, background processes should be 
liberally sprinkled with YIELD_CPU calls. 

When the Scheduler is invoked, it saves the state of the current process and 
selects the next process to run by examining the pool of ready processes. If 
the new process requires that code or data be loaded into memory, the 
Memory Manager process is launched. If the Memory Manager is already 
working on a process, the Scheduler selects the highest priority process In the 
ready queue that does not need anything swapped. 

3.6 Process Termination 

A process terminates under one of the following conditions: 

• It calls TERMINATE_PROCESS. 

' It reaches an 'END.' statement. 

• It is referred to in a KILL_PROCESS call. 

• Its father process terminates. 

• It runs Into an abnormal condition. 

When a process begins to terminate, a SYS_TERMINATE exception condition Is 
signaled to the terminating process and all of the processes It has created. 
By means of the DECLARE_EXCEP_HDL call (described In Chapter 5), any 
process can create an exception handler to catch the terminate exception and 
clean up before terminating. The SYS_TERM1NATE exception handler will be 
executed only once. If an error occurs while the handler Is executing, the 
process terminates immediately. 
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A process can call KILL_PR0CESS on any user process whose Procjd is 
known. TERMINATE_PR0CESS, on the other hand, terminates the process that 
called it (and its descendants). TERMINATE_PR0CESS also allows an event to 
be sent to the father of the terminating process if a local event channel was 
specified in the MAKE_PROCESS call. 

Termination involves the following steps: 

1. Signal the SYS_TERM1NATE exception on the terminating process. 

2. Execute the user's exception handler, if any. 

3. Instruct all sons of the current process to terminate. 

4. Close all open files, data segments^ipes, and event channels left open by 
the user process. 

5. Send the SYS_SON_TERM event to the father of the terminating process 
if a local event channel exists. 

6. Wait for all the sons to finish termination. 

3.7 A Process-Handling Exanjple 

The following programs illustrate the use of many of the process-management 
calls described in this chapter. The program Father, below, creates a son 
process and lets it run for a while. It then gives the user a chance to 
activate, suspend, kill, or gel information about the son. 

PROGRAM Father; 

USES (*$U Source :SysCall. Ob j*) SysCall; 

VAR ErrorCode : INTEGER; (*error returns from system calls 
proc_id:LONGINT; (* process global identifier 
prognarae: Pathname; (* program file to execute 
nulliNameString; (* program entry point 

Info_Rec:ProcInfoRec; (* information about process 
icINTEGER; 
Ansi»er:CHAR; 
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BEGIN 

ProgNanB:=*SON.OBJ'; (• this program is defined belo*r») 

Null:="; 

riAKE_PROCESS(ErrorCode^ Proc_Id, ProgNaroe^ Null^ 0); 

IF (ErrorOodeoO) THEN 

l»RI7ELN( 'Error '^ErrorCode^' during process nanagement.'); 
FOR i:=l TO 15 DO (* Idle for a«hile «) 

BEGIN 

iRlTELN( 'Father executes for a raonient,'); 

YIELO_CPU(ErrorCode, FALSE); (* let son run *) 
END; 

iRITE('K(ill S(uspend A(ctivate I(nfo'); 
READLN(Ansier); 
CASE Answer OF 

■K'.'k': iaLL_PROCESS(ErrorCode.Proc_Id); 

'S'.'s': SUSPEND_PROCESS(ErrorCode,Proc_Id,TRUE (* suspend 

family *)); 

'A', 'a': AcnVATE_PROCESS(ErrorCode.Proc_Id,TRUE (* activate 

family *)); 

•I'.'i': BEGIN 

INFO_PROCESS(ErrorCode^ Proc_Id^ Inf o_Rec); 

•RI7ELN('Son"s name is '^Info.Rec.ProgPathNarae); 

END; 
END; 
IF (ErrorCodeoQ) THEN 

KRITELNC "Error '.ErrorCode, ' during process management.'); 

END. 

The program Son is: 

PROGRAM Son; 

USES (*$U Source :SysCall. Ob j*) SysCall; 

VAR Errorcode:lNTEGER; 

null:NameString; 
BEGIN 

iHILE TRUE DO 
BEGIN 

URITCLNCSon executes for a moment,'); 
YiaD_CPU(ErrorCode. FALSE); (*let father process run*) 

END; 
END. 
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3.8 Process system Calls 

This section describes the Operating System calls that pertain to process 
control. A sumnDary of all the Operating System calls can be found In 
/^Dpendix A. The following special types are used In process-control calls: 

Pathname = STRINB[255]; 

Namestrlng = STRING[20]; 

P_s_eventblock = *s_eventblock; 

Sjeventblock = T_event_text; 

TjBvent_text = array [0.,size_etext] of longint; 

ProcInfoRec = record 

progpathname : pathname; 

global_id : longint; 

father_id : longint; 

priority : 1..255; 

state : (pactive, psuspended^ pvaiting); 

data_in : boolean 

end; 
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3.ai MAKE_PROCESS Process System call 

MAKE_PROCESS (Var ErrNum: Integer; 
Var Proc_Id:LongInt; 
Var ProgFile:Pathnaine; 

Var EntryNamerNaraBStrlng; (* NaineString = STRING[20] *) 
Evnt_Chn_Ref Num : Integer ) 

ErrNum: Error indicator 

Proc_Id: Process identifier (globally unique) 

ProgFile: Process file name 

EntryName: Program entry point 

E\/nt_Chn_RefNum: Communication channel between calling 
process and created process 

A son process is created when another process, the father process, calls 
MAKE_PROCESS. The son process executes the program identified by the 
pathname in ProgFile. If ProgFile is a null character string, the program name 
of the father process is used, A globally unique identifier for the son process 
is returned in Proc_Id. 

Evnt_cnn_RefNum is a local event channel supplied by the father process. 
Event channels are discussed in Chapter 5. The Operating System uses the 
event channel identified Xi\i Evnl_Chn_RefNum to send the father process 
events regarding the son process (for example, SYS_SON_TERM). If 
Evnt_crin_Ref?^*jm is zero, the father process is not informed when such 
events are produced. 

EntryName, if non-null, specifies the program entry point where execution is 
to begin. Because alternate entry points have not yet been defined for 
Pascal, this parameter is currently ignored. 

Any error encountered during process creation is reported in ErrNum. 
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3J&2 TERMINATE_PR0CESS Process system call 

TERmNATE_PROCESS(Var ErrNum: Integer; 

Event_Ptr : P_s_eventblk) 

ErrNum: Error indicator 

Ev/ent_Ptr: Information sent to process's creator 

A process can be ended by TERM1NATE_PR0CESS. This call causes a 
SYS_TERMINATE exception to be signaled for the calling process and for all 
of the processes it has created. The process can declare its own 
SYS_TERMINATE exception handler to handle whatever cleanup it needs to do 
before it is actually terminated by the system. When the terminate exception 
handler is entered, the exception information block contains a longint that 
describes the cause of the process termination: 

Excep_Data[0] - Process called TERMINATE_PROCESS. 

1 Process executed the 'EhO.' statement. 

2 Process called KILL_PROCESS on itself. 

3 Some other process called KILL_PROCESS on the 
terminating process. 

4 Father process is terminating. 



5 



Process made an invalid system call (that is, an 
unknown call). 



6 Process made a system call with an invalid ErrNum 
parameter address. 

7 Process aborted due to an error while trying to swap 
in a code or data segment. 

8 Process exceeded its maximum specified stack size. 

9 Process aborted due to possible lockup of the system 
by a data space exceeding physical memory size. 

10 Process aborted due to a parity error. 

There are an additional twenty-six errors that can be signaled. The entire list 
is shown at the beginning of Appendix A. 

If the terminating process was created with a communication channel, a 
SYS_SON_TERM event is sent to the terminating process's father. The 
terminating process can specify the text of the SYS_SON_TERM with the 
Event_Ptr parameter. Note that the first (O'th) longint of the event text is 
reserved by the system. When the event is sent to the father, the OS places 
the termination cause of the son process in the first longint This is the same 
termination cause that was supplied to the terminating process itself in the 
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SYS_TERMINATE exception information block. Any user-supplied data in the 
first longint of the event text is overwrittea 

If a process specifies an event to be sent in the TERMINATE_PR0CESS call 
but the process was created without a local event channel^ no event is sent to 
the father. 

If the process was created with a local event channel, an event Is sent to the 
father if the process calls TERMI^4ATE_PR0CESS with a nil Event_Ptr or if 
the process terminates by a means other than calling 7ERMINATE_PR0CESS. 
The event contains the termination cause in the first longint and zeroes in the 
remaining event text 

PjsjBventblk is a pointer to sjeventblk, defined as: 

CONST size_etext = 9; (* event text size - 40 bytes *) 
TYPE t_event_text = ARRAY CO..slze_etext] OF Longint; 
s_eventblk = t_event_text; 

If a process calls TERMINATE_PROCESS twice, the Operating System forces it 
to terminate even if it has disabled the terminate exception. 
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3.a3 INFO_PROCESS Process System Call 

IhFO_PROCESS (Var ErrNum: Integer; 
Proc_Id:Longlnt; 
Var Proc_Info:Prcx;InfoRec); 

ErrNum: Error indicator 

Proc_Id: Global identifier of process 
Proc_Info: Information about tne process Identified by 
Proc_Id 

A process can call IInFO_PROCESS to get a variety of information about any 
process known to tne Operating System. Use tne function MY_ID to get tne 
Pnocjd of tne calling process. 

PiQClnfoRec is defined as: 

TYPE ProcInfoRec = RECORD 



Pathname; 

Longlnt; 

1..255; 

(PActlve, PSuspended, Plfaiting); 

Bc»lean 



ProgPathname: 
Global_id 
Priority 
State 
Data_in 
END; 

Datajn inaicates whether tne data space of tne process is currently in 
memory. 

The procedure on the next page gets information about a process and displays 
some of it. 
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PROCEDURE Oisplay_InfO(Proc_Id:LONGINT); 
VAR ErrorCode : INTEGER; 

Inf o_Rec : Procinf oRec; 
BEGIN 

INFO_PROCESS(ErrorCocle. Proc_Icl, Inf o_Rec); 
IF (ErrorCode=100) THEN 

«RITELN( 'Attempt to display info atxxit nonexistent 
process.") 
ELSE 
BEGIN 

WTH Info_Rec 00 
BEGIN 

iRITELNC program name: '^ProgPathName); 
•RITELNf global id: ^Globaljd); 
iRITELN(' priority: Apriority); 
•RITEC state: '); 
CASE State OF 

PActive : iRITELN( ' active ' ); 
PSuspended: iRITELNC 'suspended'); 
Piaiting: iRITELN( ' waiting' ) 
END 
END 
END 
END; 
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3.8.4 KILL_PR0CESS Process system Call 

KILLJJROCESS (Var ErrNum: Integer; 
Proc_Id:LongInt) 

ErrNum: Error indicator 

Proc_Id: Process to be killed 

KILL_PROCESS kills the process referred to by Proc_Id and all of the 
processes in its subtree. The actual termination of the process does not occur 
until the process is in one of the following states: 

• Executing in user mode. 

• Stopped due to a SUSPEND_PROCESS call. 

• Stopped due to a DELAY_TIME call. 

• Stopped due to a WAIT_EVENT_CHN or SEhO_EVENT_CHN call, or 
READ_DATA or WRITE_DATA to a pipe. 
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3.8.5 SL»SPEND_PRCK)ESS Process system Call 

SUSPEND_PROCESS (Var ErrNuTO: Integer; 
Proc_Id:LongInt; 
Susp_Famlly :Boolean) 

ErrNum: Error indicators 

Proc_Id: Process to tje suspended 

Susp_Family: If true, suspend the entire process subtree 

SUSPENDJPROCESS allows a process to suspend (block) any process in the 
system. The actual suspension does not occur until the process referred to by 
Proc_Id is in one of the following states: 

• Executing in user mode 

• Stopped due to a DELAY_TIME call 

• Stopped due to a WA1T_EVENT_CHN call 

Neither expiration of the delay time nor receipt of the awaited event causes 
a suspended process to resume execution. SUSPEND_PROCESS is the only 
direct way to block a process. Processes, however, can become blocked during 
I/O, by the timer (see DELAY_TIME), or for many other reasons. 

If Siisp_Famlly is true, the Operating system suspends both the process 
referred to by Procjd and all of its descendents. If Susp_Famlly is false, 
only the process identified by Procjd is suspended. 
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3.8.6 ACTIVA7E_PR0C€SS Piocess System call 

ACnVATE_PROCESS(Var ErrNum: Integer; 
Proc_Id:LongInt; 
Act_Fainily :Boolean) 

ErrNum: Error indicator 

Proc_Id: Process to be activated 

Act_Family: If true, activate the entire process subtree 

To awaken a suspended process, call ACTIVATE_PRCCESS. A process can 
activate any other process in the system. Note that ACTIVATE_PROCESS can 
awaken only a suspended process. If the process is blocked for some other 
reason, ACTIVATE_PROCESS cannot unblock it. If Act_Family is true, 
ACTIVATE_PRCK)ESS also activates all the descendents of the process referred 
to by Procjd. 
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3.8.7 SETPRiORlTY.PRCr^ESS Process system Call 

SETPRIORITY_PROCESS(Var ErrNum: Integer; 

Proc_Id : Longint; 
Ne«_Prlority : Integer ) 

ErrNum: Error indicator 

Proc_Id: Glottal id of process 

New_Priority: Process's new priority number 

SETPRICRITY_PR0CESS changes the scheduling priority of the process 
referred to by Procjd to New_Priority. The priority value must be between 1 
and 225. (Operating System processes execute with priorities between 226 
and 255.) The higher the priority^ the more likely the process is to be allowed 
to execute. 
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3.8.8 YIELD_CPU Process System Call 

YIELD_CPU(Var ErrNuro: Integer; 
To_Any: Boolean) 

ErrNum: Error indication 

To_Any: Yield to any process^ or only nigner or equal 
priority 

Background processes snould use YIELD_CPU often to allow otner processes to 
execute wnen they need to. Successive yields by processes of the same 
priority result in a "round robin" scheduling of the processes. If To_Any is 
true^ YIELDjCPU causes the calling process to yield the CPU to any other 
ready process. If To_/Nny is false, YIELD_CPU causes the calling process to 
give the CPU to any other ready-to-execute process with an equal or higher 
priority. If no process meets the To_Any criterion, the calling process simply 
continues execution. 
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3.8.9 MY_ID Process System Call 

riY_ID:Longint 

MYJD is a function mat returns the unique global identifier (a longint) of the 
calling process. A process can use MYJD to perform process handling calls 
on itself. 

For example: 

SetPrldrlty_Process(ErrNunuMy_Id, 100) 

sets the priority of the calling process to 100. 
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Memory Management 



Every process has a set of code segments and data segments which are in 
physical memory when they are used. The logical address used by the process 
must be translated into the physical address used by the memory controller. 
This function is handled by the memory management unit (MMU). 

4.1 Data Segments 

Each process has a data segment that the Operating System automatically 
allocates to it for use as a stack. The stack segment's internal structures are 
managed by the hardware and the Operating System. 

A process can acquire additional data segments for uses such as heaps and 
interprocess communication. These additional data segments can be private 
(or local ) data segments or shared data segments. Private data segments 
can be accessed only by the creating process. When the process terminates, 
any private data segments still in existence are destroyed. Sharecl data 
segments can be accessed by any process that opens those segments. 

The Operating System requires that data segments be in physical memory 
before the data are referenced. The Scheduler automatically loads all of the 
data segments that the program says it needs. It is the responsibility of the 
programmer to ensure that the program declares all its needs by associating 
itself with the needed data segments before they are needed. 

This process of association is called binding. A program can bind a data 
segment to itself in several ways. When a program creates a data segment by 
using the MAKE_DATASEG call, the segment is automatically opened and 
bound to the program. If a program needs to open a segment that was 
created by another program, the OPEN_DATASEG call is used. That call binds 
the segment to the calling process, as well as opening the segment for the 
process. Since there may be times when a process needs to use more data 
segments than can be bound at one time, the UNBIlsD_DATASEG call Is 
provided to mbind the data segment without closing it. The program can then 
use BIND_DATASEG to bind another data segment to the program. 

The Operating System views all data segments except the stack as linear 
arrays of bytes. Therefore, allocation, access, and interpretation of structures 
within a data segment are the responsibility of the program. 

4.2 The Logical Data Segment Number 

The address space of a process allows up to 16 data segments bound to a 
process at the same time, in addition to the stack. Each bound data segment 
is associated with a specific region of the address space by means of a 
Logical Data Segment Number (LDSN). See Figure 3-1 for an illustration of 
the address space of a process. While a data segment is bound to the process, 
it is said to be a member of the working set of the process. 
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The process associates a data segment with a specific ldsn in the 

MAKE_DATASEG or OPEN_DATASEG call. 

The LDSN^ Which has a valid range of 1 to 16, is local to the calling process. 
The process uses the LDSN to keep track of where a given data segment can 
be found. More than one data segment can be associated with the same LDSN, 
but only one such segment can be bound to a given LDSN at any instant and 
thus be a fnember of the working set of the process. 

4.3 Shared Data Segments 

Cooperating processes can share data segments. Shared segments cannot be 
larger than 128 Kbytes In length. As with local data segments, the segment 
creator assigns the segment a File System pathname. All processes that share 
that data segment then use the same pathname. If the shared data segment 
contains address pointers to data within the segment, the cooperating 
processes must also use the same LDSN with the segment. This ensures that 
all logical data addresses referencing locations within the data segment are 
consistent for the processes sharing the segment. A shared data segment is 
permanent until explicitly killed by a process. 

4^4 Private Data Segments 

Data segments can also be private to a process. In this case, the maximum 
size of the segment can be greater than 128 Kbytes. The actual maximum 
size depends on the amount of physical memory in the machine and the 
number of adjacent LDSNs available to map the segment. The process gives 
the desired segment size and the base LDSN to map the segment. The 
Memory Manager then uses ascending adjacent LDSNs to map successive 128 
Kbyte chunks of the segment. The process must ensure that enough 
consecutive LDSNs are available to m^ the entire segment. 

Suppose a process has a data segment already bound to LDSN 2. If the 
program tries to bind a 256 Kbyte data segment to LDSN 1, the Operating 
System returns an error because the 256 Kbyte segment needs two consecutive 
free LDSNs. Instead, the program should bind the segment to LDSN 3 and the 
system automatically also uses LDSN 4. 

4.5 CXKle Segments 

Division of a program into multiple code segments (swapping units) is dictated 
by the programmer through commands to the Compiler and Linker. The MMU 
registers can map up to 106 code segments. 

4.6 Swapping 

When a process executes, the following segments must be In physical memory: 

• The current code segment 

• All the data segments In the process working set (the stack and all bound 
data segments) 

The Operating System ensures that this minimum set of segments is in physical 
memory before the process is allowed to execute. If the program calls a 
procedure in a segnent not in memory, a segment swap-in request is initiated. 
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In the simplest case, this request only requires the system to allocate a Dlock 
of physical memory and to read in the segment from the disk. In a worse 
case, the request may require that other segments be swapped out first to 
free up sufficient memory. A clock algorithm is used to determine which 
segments to swap out or replace. This process is invisible to the program. 

4.7 Memory Management System Calls 

This section describes all the Operating System calls that pertain to memory 
management. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in memory management 
calls: 

Pathname = STRING[255]; 

Tdstype = (ds_shared^ ds_prl\/ate); 

DsInfoRec = Record 

inefn_slze:longint; 

dlsc_size : longint; 

nunt)_open : integer; 

LDSN: Integer; 

boundF:txx)lean; 

presentF : boolean; 

creatorFrDoolean; 

rwaccess : boolean; 

segptr: longint; 

volname:e name; 
end; 
E_name = string [32]; 
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A.7.1 MAKE_DATASEG Memory Management System Call 

MAKE_DATASEG (Var ErrNuin:Integer; 
Var Segnarae: Pathname; 

Mem_Size^ Disk_Size:LongInt; 
Var RefNum: Integer; 
Var SegPtr:LongInt; 

Ldsn: Integer 

Dstype:Tdstype) 

ErrNum: Error indicator 

Segname: Pathname of data segment 

Mein_Size: Bytes of memory to de allocated to data segment 

Disk_Size: Bytes on disk to be allocated for swapping segment 

RefNum: Identifier for data segment 

SegPtr Address of data segment 

Ldsn: Logical data segment number 

Dstype: Type of dataseg (shared or private) 

MAKE_DATASEG creates the data segment identified by the pathname^ 
Segname, and opens it for immediate read-write access. Segname is a File 
System pathname. 

The parameter Mem_si2e determines how many bytes of main memory are 
allocated to the segment. The actual allocation takes place in terms of 
512-byte pages. If the data segment is private (Dstype is ds_prlvate), 
Mem_Si2e can be greater than 128 Kbytes, but you must ensure that enough 
consecutive LDSNs are free to map the entire segment. 

Diskjslze determines the number of bytes of swapping space to be allocated 
to the segment on disk. If Disk_Size is less than Mem_Size, the segment 
cannot be swapped out of main memory. In this case the segment is memory 
resident until it is killed or until its size in memory becomes less than or 
equal to its Dlsk_Slze (see SI2E_DATASEG). The application programmer 
should be aware of the serious performance implications of forcing a segment 
to be memory resident. Because the segment cannot be swapped out, a new 
process may not be able to get all of its working set into memory. To avoid 
thrashing, each application should ensure that all of its data segments are 
swappable before it relinquishes the attention of the processor. 

TX\'^ calling process associates a Logical Data Segment Number (LDSN) with 
the data segment. If this LDSN is bound to another data segment at the time 
of the call, the call returns an error. 

RefNum is returned by the system to be used in any further references to the 
data segment. The Operating System also returns SegPtr, an address pointer to 
be used to reference the contents of the segment. SegPtr points to the base 
of the data segment. 

Any error conditions are returned in Errfsium. 
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When a data segment is created. It Immediately becomes a member of the 
working set of the calling process. You can use UNBIlsD_DATASEG to free 
the LDSN. 
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^J2 KILL_DATASEG Memory Management System Call 

KILL_DATASEG (Var ErrNura: Integer; 
Var Segnanie: Pathname) 

ErrNum: Error indicator 

Segname: Name of data segment to be deleted 

wnen a process is finished with a shared data segment, it can issue a 
KILL_DATASEG call for that segment. (KILL_DATASEG cannot be used on a 
private data segment.) If any process, including the calling process, still has 
the data segment open, the actual deallocation of the segment is delayed until 
all processes have closed it (see CLOSEJDATASEG). During the interim period, 
however, after a KILL_DATASEG call has been issued but before the segment 
is actually deallocated, no other process can open that segment. 

K1LL_DATASEG does not affect the membership of the data segment in the 
working set of the process. The RefNum and SegPtr values are valid until a 
CLOSE_DATASEG call is issued 

One important note: normally, when a data segment is closed, the contents 
are written to disk as a file with the pathname associated with the data 
segment. If, however, the program calls KILL_DATASEG on the data segment 
before closing it, the contents of the data segment are not written to disk and 
are lost when the segment is closed. 
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nJ3 CPEN_DATASEG Memory Management system call 

OPEN_DATASEG (Var ErrNuni: Integer; 
Var Segname: Pathname; 
Var RefNum: Integer; 
Var SegPtr:LongInt; 
Ldsn: Integer) 

ErrNum: Error indicator 

Segname: Name of data segment to be opened 

RefNum: Identifier for data segment 

SegPtr Pointer to contents of data segment 

Ldsn: Logical data segment number 

A process can open an existing shared data segment with CPEN_DATASEa 
The calling process must supply the name of the data segment (Segname) and 
the Logical Data Segment Number to be associated with it. The LDSN given 
must not have a data segment currently bound to it. The segment's name is 
determined by the process that creates the data segment; it cannot be null. 

The Operating System returns both RefNum, an identifier for the calling 
process to use in future references to the data segment, and SegPtr. an 
address pointer used to reference the contents of the segment. 

When a data segment is opened, it immediately becomes a member of the 
working set of the calling process. The access mode of the newly opened 
segment is Readonly. You can use SETACCESS_DATASEG to change the 
access rights to Readwrlte. You can use UNBIND DATASEG to free the 
LDSN. 

You cannot use CPEN on a private data segment, since calling CLOSE on a 
private data segment deletes it. 
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t^JA CLOSE_DATASEG Memory Management System Call 

CLOSE_DATASEG (Var ErrNum : Integer; 
RefNum: Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

CLOSE_DATASEG terminates any use of RefNum for data segment operations. 
If the data segment is bound to a Logical Data Segment Number, 
CLOSE_DATASEG frees tnat LDSN. Tne data segment is removed from the 
working set of the calling process. ReffMum is made invalid. Any references 
to the data segment using the original SegPtr will have unpredictable results. 

If RefNum refers to a private data segment, CLOSE_DATASEG also kills the 
data segment, deallocating the memory and disk space used for the data 
segment. If ReflMum refers to a shared data segment, the contents of the 
data segment are written to disk as if FLUSH_DATASEG had been called. (If 
KILL_DATASEG is called before CLOSE_DATASEG, the contents of the data 
segment are thrown away when the last process closes the data segment.) 

The following procedure sets up a heap for LlsaGraf using the memory 
management calls: 

PROCEDURE InltOataSegForLisaGraf (var ErrorCode: integer); 

CX)NST HeapSize=16384; (* 16 KBytes for graphics heap *) 
DiskSize=16384; 

VAR HeapBuf :LONGINT; (* pointer to heap for LisaGraf *) 
GrafHeap:PathNanie; (* data segment path name *) 

Heap_Refnum: INTEGER; (* refnum for heap data seg *) 

BEGIN 

GrafHeap : = " grafheap • ; 

ciPEN_DATASEG(ErrorCode, GrafHeap, Heap_Ref nunu HeapBuf, l); 

IF (Errorcode<>0) THEN 

BEGIN 

WRITELN( 'Unable to open", Grafheap, 'Error is ', ErrorCode) 

END 

asE 

InltHe^(POINTER(He^DBuf ), POINTER(He^)Buf *He€^ize), 
sHeapError); 
END; 
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4.7.5 FLUSH_DATASEG Memory Management System Call 

FLUSH_OATASEG (Var ErrNum: Integer; 
Ref Num.- Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

FLUSH_DATASEG writes the contents of the data segment identified by 
Reflvlum to the disk. (Note that CLOSE_DATASEG automatically flushes the 
data segment before closing it^ unless KILLJDATASEG was called first.) This 
call has no effect upon the memory residence or binding of the data segment. 



4-9 



operating System Reference Manual Memory Management 

4.7.6 SIZE_DATASEG Memory Management System Call 

SIZE_DATASEG (Var ErrNum : Integer; 

Refnum: Integer; 

DeltaheniSize :LongInt; 
Var Neiitteii61ze:LongInt; 

OeltaOlskSize : Longint; 
Var NewOiskSlze: Longint) 

ErrNum: Error indicator 

RefNum: Data segment identifier 

DeltaMemSize: Amount in bytes of change in memory 

allocation 

NewMeiTtSize: New actual size of segment in memory 

DeltaDiskSize: Amount in bytes of change in disk allocation 

NewDiskSize: New actual disk (swapping) allocation 

SIZE_DATASEG changes the memory and/or disk space allocations of the data 
segment referred to by RefNum. Both DeltaMemSize and DeltaDiskSize can 
be either positive^ negative^ or zero. The changes to the data segment take 
place at the high end of the segment and do not destroy the contents of the 
segment^ unless data are lost in shrinking the segment. Because the actual 
allocation is done in terms of pages (512-byte blocks), the NewMemSlze and 
NewDlskSize returned by SIZE_DATASEG may be larger than the old size plus 
delta size of the respective areas. 

If the NewDiskSize is less than the NewMemSize, the segment cannot be 
swapped out of memory. The application programmer should be aware of the 
serious performance implications of forcing a segment to be memory resident. 
Because the segment cannot be swapped out, a new process may not be able 
to get all of its working set into memory. To avoid thrashing, each 
application should ensure that all of its data segments are swappable before it 
relinquishes the attention of the processor. 

If the necessary adjacent LDSNs are available, SIZE_DATASEG can increase 
the size of a private data segment beyond 128 Kbytes. 
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^JJ INFOJDATASEG Memory Management system call 

INFO_OATASEG (Var EnNuBi: Integer; 
RefNuRi: Integer; 
Var DsInfo:DsInfoRec) 

Errt^jm: Error indicator 

RefNum: Identifier of data segment 

Dslnfo: Attributes of data segment 

INFO_DATASEG returns information about a data segment to tne calling 
process. Tne structure of the DsInfoRec record is: 

RECORD 

Heiii_Size:LongInt (« Bytes of memory allocated to data segment * 
DlscjSlzerLonglnt (* Bytes of disk space allocated to segment * 
NumbOpen: Integer (* Current nunber of processes with segment open • 
Ldsn: Integer (* LDSN for segment binding * 

BoundF: Boolean (* True if segment is bound to LDSN of calling proc « 
PresentF .-Boolean (* True if segment Is present in memory » 
CreatorF:Booleanm (* True if the calling process is the creator * 
(« of the segment * 

RVAccesszBoolean (* True if the calling process has Ifirite access * 
(* to segment * 

END; 
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lUA INFOJLDSN Memory Management system Call 

INFO_LDSN ( Var ErrNum: Integer; 
Ldsn: Integer; 
Vaif RefNuro: Integer) 

ErrNum: Error irKlicator 

Ldsn: Logical data segment number 

RefNum: Data segnent identifier 

INFOJ_DSN returns the refnum of the data segment currently hound to Ldsa 
You can then use INFO_DATASEG to get information about that data segment. 
If the LDSN specified is not currently bound to a data segment, the refnum 
returned is -1. 
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fl.7.9 INF0_ADORESS Memory Management System Call 

INFO_ADORESS (Var ErrNum: Integers- 
Address rLongint; 
Var RefNum: Integer) 

ErrNun: Error indicator 

Address: The address about wtiich the program needs information 

RefNum: Data segment identifier 

This call returns the refnwm of the currently Dound data segment that 
contains the address given. 

If no data segment that contains the address given Is currently bound to the 
calling process, an error indication is returned in ErrNum. 
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4.7.10 MEM.INFO Memory Management system call 

MEM_INFO (var ErrNum:Integer; 
Var Svapspace; 
Dataspace; 
Cur_codeslze; 
Haxjcodeslze : Longlnt ) 

ErrNum: Error indicator 

Swapspace: Amount^ in bytes^ of swappdDle system memory 

available to the calling process 
Dataspace: Amount, in bytes, of system memory that the 

calling process needs for its bound data areas, 

including the process stack and the shared 

intrinsic data segment 
Cur_codeslze: Size, in bytes, of the calling segment 
Max_codesl2e: Size, in bytes, of the largest code segment 

within the address space of the calling process 

This call retrieves information about the memory resources used by the calling 
process. 
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4.7.11 SETACCESS_DATASEG Memory Management System Call 

SETACCESS_DATASEG (Var ErrNum : Integer; 

RefMum: Integer; 
Readonly : Boolean) 

ErrNum: Error indicator 
RefNum: Data segment identifier 
Readonly: Access mode 

A process can control the kinds of access it is allowed to exercise on a data 
segment with the SETACCESS_DATASEG call. Refnum Is the identifier for 
the data segment, if Readonly Is true, an attempt Oy the process to write to 
the data segment results in an address error exception condition. To get 
readwrite access, set Readonly to false. 
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4w7.l2 BIND_DATASEG and UNBIND_DATASEG Memory Management system calls 

BIND_OATASEG(Var ErrNum: Integer; 
RefNum: Integer) 

U^BIND_DATASE6(Var ErrNum: Integer; 
Ref^Mn: Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

BnND_DATASEG binds the data segment referred to by RefNum to its 
associated Logical Data Segment Number(s). UNBINDJDATASEG unbinds the 
data segment from its LDSNs. BIND_DATASEG causes the data segment to 
become a member of the current working set. At the time of the 
BIhD_DATASEG call, the necessary LDSNs must not be bound to a different 
data segment. UNBIND_DATASEG frees the associated LDSNs. A reference to 
the contents of an unbound segment gives unpredictable results. 
OPENJDATASEG and MAKEJDATASEG define which LDSNs are associated 
with a given data segment. 
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Exceptions and Events 



Processes have several ways to keep informed about the state of the system. 
Normal process-to-process communication and synchronization employ pipes^ 
shared data segments, or events. Abnormal conditions, including those your 
program may define, employ exceptions (interrupts). Exceptions are signals to 
which the process can respond in a variety of ways under your control. 

5.1 Exceptions 

Normal execution of a process can be interrupted by an exceptional condition 
(such as division by zero or reference to an Invalid address). Some error 
conditions are trapped by the hardware and some by the system software. The 
process itself can define and signal exceptions of your choice. 

When an exception occurs, the system first checks the state of the exception. 
The three exception states are: 

• Enabled 

• Queued 

• Ignored 

If a system-defined exception is enabled, the system looks for an associated 
user-defined handler. If none is found, the system invokes the default 
exception handler, which usually aborts the process that generated the 
exception. If a user-defined exception is enabled, the system invokes the 
associated user-defined exception handler. You create a new exception by 
declaring and enabling a handler for it. 

If the state of the exception is queued the exception is placed on a queue. 
When the exception is subsequently enabled, the queue is examined and the 
appropriate exception handler Is Invoked. Processes can flush the exception 
queue. 

If the state of the exception is ignored the system detects the occurrence of 
the exception, but the exception is neither honored nor queued. Note that 
ignoring a system-defined exception has uncertain effects. Although you can 
cause the system to ignore even the SYS_TERMINATE exception, that 
capability is provided so that your program can clean up before terminating. 
You cannot set your program to ignore fatal errors. 

Invocation of the exception handler causes the Scheduler to run, so it is 
possible for another process to run between the signaling of the exception and 
the execution of the exception handler. 
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5JZ SystefTHDefJned Exceptions 

Certain exceptions are predefined by the Operating System. These include: 

• Division by zero (SYS_ZERO_DIV). The default handler aborts the process. 

• Value out of bounds (that is. range check error) or illegal string index 
(SYS_VALUE_OOB). The default handler aborts the process. 

• Arithmetic overflow (SYS_OVERFLOW). The default handler aborts the 
process. 

• Process termination (SYS_TERMINATE). This exception is signaled when a 
process terminates, or when there is a bus error, address error, illegal 
instruction, privilege violation, or 1111 emulator error. The default handler 
does nothing. This exception is different from the other system-defined 
exceptions in that the program always terminates as soon as the exception 
occurs. In the case of other (non-fatal) errors, the program is allowed to 
continue until the exception is enabled. 

Except where otherwise noted, these exceptions are fatal if they occur within 
operating System code. The hardware exceptions for parity error, spurious 
interrupt, and power failure are also fatal. 

5.3 Exception Handlers 

A user-defined exception handler can be declared for a specific exception. 
This exception handler is coded as a procedure but must follow certain 
conventions. Each handler must have two input parameters: Environment_Ptr 
and Data_Ptr. The Operating System ensures that these pointers are valid 
when the handler is entered, Environnnent_Plr points to an area in the stack 
containing the interrupted environment: register contents, condition flags, and 
program state. The handler can access this environment and can modify 
everything except the program counter, register A7, and the supervisor state 
bit in the status register. Data_Ptr points to an area in the stack containing 
information about the specific exception. 

Each exception handler must be defined at the global level of the process, 
must return, and cannot have any EXIT or global GOTO statements. Because 
the Operating System disables the exception before calling the exception 
handler, the handler should re-enable the exception before it returns. 

If an exception handler for a given exception already exists when another 
handler is declared for that exception, the old handler becomes dissociated 
from the exception. 

An exception can occur during the execution of an exception handler. The 
state of the exception determines whether it is honored,placed on a queue, or 
ignored. If the second exception has the same name as the exception that is 
currently being handled and its state is enabled, a nested call to the exception 
handler occurs. (The system always disables the exception before calling the 
exception handler, however. Therefore, nested handler calling occurs only if 
you explicitly enable the exception.) 
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There is an exception-occurred flag, Ex_occurrecl_t for every declared 
exception; it is set whenever the corresponding exception occurs. This flag 
can be examined and reset using the INF0_EXCEP system call, once the flag 
is set it remains set until FLUSH_EXCep is called. 

The following program fragment gives an example of exception handling. 

PROCEDURE Handler (Erwironment_Ptnp_envJ)Ik; 

Data_RKp_ex_data]i; 
VAR EnNum:INTEGER; 
BEGIN 

(*Envlronment_Ptr points to a record containing the progiam *) 
("counter and all registers. Data_Ptr points to an array of 12 *) 
(*longints that contain the event header and text if this handler «) 
(*is associated with an event-call channel (See below) «) 



ENABLE_EXCEP(ermum^xcep_name); 

END; 

BEGIN (*Main program*) 



Excep_name:-'EndOfDoc; 
DECLARE_EXCEP_HDL(ermum^xcep_name,flHandler); 



SlGNAL_EXCEP(erfmum^xcep_namejexcep_data); 



At the time the exception handler is invoked for a SYS_TERMINATE 
exception, the stack is as shown in Figure 5-1. 
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Figure 5-1 
Stack at Exception Handler invocation 

The Exception Data Block given here reflects the state of the stack upon a 
SYS_TERMINATE exception. The Term_Ex_Data record (described in Appendix 
A) gives the various forms the data block can take. The Excep_Kind field (the 
first, or 0th, longint) gives the cause of the exception. The status register and 
program counter values in the data block reflect the true (current) state of 
these values. The same data in the Environment block reflects the state of 
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these values at the time the exception was signaled^ not the values at the 
time the exception actually occurs. 

For SYS_ZERO_DIV, SYS_VALUE_CXB, and SYS_OVERFLOW exceptions, the 
nard_Ex~Data~ record described in Appendix A gives the various forms that 
the data block can take. 

In the case of a bus or address error, the PC (program counter) can be 2 to 10 
bytes beyond the current instruction. The PC and A7 cannot be modified by 
the exception handler. 

When a disabled exception is re-enabled, a queued exception may be signaled. 
In this case, the exception environment reflects the state of the system at the 
time the exception was re-enabled, not the time at which the exception 
occurred. 

5.4 Events 

An event is a piece of information sent by one process to another, generally 
to help cooperating processes synchronize their activities. An event is sent 
through a kind of pipe called an event channel. The event is a fixed-size 
data block consisting of a header and some text. The header contains control 
information, the identifier of the sending process, and the type of the event. 
The header is written by the system, not the sender, and Is readable by the 
receiving process. The event text is written by the sender; its meaning is 
defined by the sending and receiving processes. 

There are several predefined system event types. The predefined type "user" is 
assigned to all events not sent by the Operating System. 

5.5 Event Channels 

Event channels can be viewed as higher-level pipes. One important difference 
Is that event channels require fixed-size data blocks, whereas pipes can 
handle an arbitrary byte stream. 

An event channel can be defined globally or locally. A global event channel 
has a globally defined pathname catalogued in the File System and can be 
used by any process. A local event channel, however, has no name and is 
known only by the Operating System and the process that opened it Local 
event channels can be opened by user processes only as receivers. A local 
channel can be opened by the father process to receive system-generated 
events pertaining to its son. 

There are two types of global and local event channels: event-wait and 
event-call. If the receiving process Is not ready to receive the event, an 
event-wait type of event channel queues an event sent to it . An event-call 
type of event channel, however, forces its event on the process, in effect 
treating the event as an exception. In that case, an exception name must be 
given when the event-call event channel is opened, and an exception handler 
for that exception must be declared. If the process reading the event-call 
channel is suspended at the time the event is sent, the event Is delivered 
when the process becomes active. 
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When an event channel Is created^ the Operating System preallocates enough 
space to the channel for typical interprocess communication. If 
SEhD_EVENT_CHN Is called when the channel does not have enough space for 
the events the calling process Is blocked until enough space is freed up. 

If WAIT_EVENT_CHN Is called when the channel is empty, the calling process 
is blocked until an event arrives. 

The following code fragments use event-wait channels to handle process 
synchronization. Operating System calls used in these program fragments are 
documented later in this chapter. 

Process A: 



chnjiame := 'event_channel_r; 

exception: = "; 

receiver := TRUE; 

OPENJEVENTJCHN (eiTint, chnjiame^ ref numl, exception, receiver ); 

chn_nanie := 'event_channel_2*; 

receiver := FALSE; 

OPEN_EVENT_CHN (errint^ chn_naBB^ refnuRC^ exception receiver ); 

waitlist. length := 1; 

waitlist. refnuRi[0] := refnuml; 

REPEAT 

eventljjtr*.[0] := agreed_upon_value; 

interval. sec := 0; (* send event immediately «) 

interval. msec := 0; 

SEND_EVENT_CHN (errint,refnum2,eventlj)tr^ interval^ clktirae); 

•AIT_EVENT_CHN (errint, waitlist. refnuro_signaling, event2_ptr); 



(« processing performed here «) 
UNHL. AllOone; 
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Process B: 



chn_nanie := *event_channel_2V 

exception := "; 

receiver := TRUE; 

OPEN_EVENT_CHN (eirlnt^ chn_namB, xefnufflZ^ exceptiorv receiver); 

chnjrame := 'event_channel_r; 

receiver := FALSE; 

OPEN_EVENT_CHN (errlnt, cTYi.name^ ref numl, exception, receiver); 

•aitlist. length := 1; 

«aitllst.refnum[0] := refnuml; 

REPEAT 

event2j]tr*.[0] := agreedjupon_value; 

interval. sec := 0; (* send event Imniedlately *) 

Interval. msec := 0; 

•AIT_EVENT_CHN (errlnt, ipaltlist, ref num_signallng, eventljjtr); 



(* processing performed here *) 



SEND_EVENT_CHN (errlnt, ref numZ^ event2_ptr^ interval, clktlrae); 
UNHL AllDone; 



The order of execulloi of tr« two processes is the same regardless of the 
process priorities. Process switch always occurs at the WAIT_EVENT_CHN 
call. 

In the following example using event-call channels, process switch may occur 
at different places in the programs. Process A calls YIELDjCPU, which gives 
the CPU to Process B only if Process B is ready to run. 
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Process A: 

PROCEDURE Handler(Envj)tr:p_envj>lK; 
Datajitr:pjexjclBta); 



BEGIN 

event2_ptr".[0] := agreedjupon.value; 
(* processing perfoned r«ie •) 



interval. sec := 0; (* send event iMBdlately *) 

interval .msec :> 0; 

SEN)_EVEKT_CHN (errlnt,refnuiie,event2jytr, interval^ clktlme); 

to_any :» true; 

YIELDJDPU (errlnt^tojany); 

END; 

BEGIN (» nain prograir*) 



DECL/«EJE)(CEP_HDL (errint^excep_naniB_l,aHandler); 

chn.naiiie := 'eventjchannelj'; 

exception :« exDep_naiii8_l; 

receiver := TRUE; 

OPEN_EVENT_CHN (errlnt^ chn_naraB^ ref numl^ exception, receiver); 

chn.name := *event_channel_2'; 

receiver := FALSE; 

exception:- *•; 

OPEN_EVENT_CHN (errlnt^ chnjiaiK^ refnui^ exoeptioa receiver); 

SENDJEVENTJCHN (enlnt^ refnume, event2_ptr, IntervaL clktlme); 

tojany :« true; 

YiaojCPU (errlnt, to_any); 
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Process B: 

PROCEDURE Handler(Enwj)tr:p_env_DlK; 
Deta_ptr :p_ex_data); 



BEGIN 

event2jptr".[0] := agreed_upon_value; 



(* processing performed here *) 



interval. sec := 0; (* send event inmedlately *) 

interval. msec := 0; 

SEND_EVENT_CHN (eirint, refnuTOl, event2_ptr, interval, clktlHie); 

to any := true; 

YIELD_CPU (errint,to_any); 

END; 



BEGIN (*riain program *) 

DECU«E_EXCEP_HDL (errint, excep_nanie j_l, aHandler ) 

chn_namB := •event_cnannel_l'; 

exception: = excep_nanie_l; 

receiver "= FALSE; 

exception := "; 

OPEN_EVENT-CHN (errint, chnjiaroe, refnuml, exception, receiver); 

chn_name := •event_channel_2'; 

receiver := TRUE; 

OPEN_EVENT_CHN (errint, cnn_name, ref nuRi2, exceptioa receiver); 



END. 
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5.6 The System Clock 

A process can read the system clock time, convert it to local time, or delay 
its own continuation until a given time. The year, month, day, hour, minute, 
second, and millisecond are available from the clock. The system clock is set 
up through the Workshop shell. For more information, see the workshop user's 
GuJcfe for the Lisa, 

5.7 Exception Management System Calls 

This section describes all the Operating System calls that pertain to exception 
maiagement A siffTwnary of all the pirating System calls can be found in 
Appendix A. The following special types are used in exception management 
calls: 

T_ex_narae = STRING[16]; 

Longadr = "longint; 

T_ex_data = Array [0..11] of longlnt; 

T_ex_sts = Record 

ex_0Gcurred_f .-boolean; 

ex_state : t_ex_state; 

nuBLexcep : Integer; 

hdl_adr:longadr; 
end* 
T_ex_state = (envied, queuect ignored); 
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5.7.1 DECLARE_EXCEP_HDL ExcepUon Management System Call 

DECLARE_EXCEP_HDL ( Var ErrNum: Integer; 

Var Excep_Name:t_ex_name; 
Entry_Polnt :LongAdr ) 

ErrNum: Error indicator 

Excep_Nafne: Name of exception 
Entry_Point: Address of exception handler 

IDECLARE_EXCEP_HDL sets the Operating System so that the occurrence of 
the exception referred to by Excep_Name causes the execution of the 
exception handler at Entry_PolnL 

Excep_Name is a character string name with up to 16 characters that is 
locally defined in the process and known only to the process and the Operating 
System. If Entry_Polnt is nil and ExDep_Name specifies a system exception, 
the system default exception handler is used. Any previously declared 
exception handler is dissociated ti'j this call. The exception Itself is 
automatically enabled. 

If any Excep_Name exceptions are queued at the time of the 
DECLARE_EXCEP_HDL call, the exception is automatically enabled and the 
queued exceptions are handled by the newly declared handler. 

You can call DECLARE_EXCEP_HDL with an exception handler address ofnll 
to dissociate your handler from the exception. If there is no system handler 
defined, the program that signals the exception receives an error 201. 
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5.72 DISABLE_EXCEP Exception Management System Cdll 

DISABLE_EXCEP (Var ErrNun: Integer; 

Var Excep_Name:t ex_namB; 
Queue zBooleanJ 

ErrNum: Error indicator 

Excep_Name: Name of exception to be disabled 

Queue: Exception queuing flag 

A process can explicitly disable tne trapping of an exception by calling 
DIS/«LE_EXCEP. Excep_Name is the name of the exception to tse disabled. 
If Queue is true and an exception occurs^ the exception is queued and is 
handled when it is enabled again. If Queue is false^ the exception is ignored. 
When an exception handler is entered, the state of the exception in question 
is automatically set to queued. 

If an exception handler is associated through CPEN_EVENT_CHN with an 
event channel and DISABLE_EXCeP is called for that exception^ then: 

• If Queue is false, and if an event is sent to the event channel by 
SEhD^EVENTjCHN, the SENDJEVENT_CHN call succeeds, but it is 
equivalent to not calling SEhD_EVENT_CHN at all. 

• If Queue is true, and if an event is sent to the event channel by 
SEfsD_EVENT OH the SEND_EVENT_CHN call succeeds and a call to 
WAlT_EVENTjbHN receives the event, thus dequeuing the exception. 



5-12 



Cperatlng System Reference Manual Exceptions and Euents 

5.7.3 ENABLE_EXCEP ExcepUon Management System Call 

ENABLE_EXCEP (Var ErrNuni: Integer; 

Var Excep-name:t_ex_narae) 

ErrNum: Error indicator 

Excep_Na»ne: Name of exception to be enabled 

ENABLE_EXCEP causes an exception to be handled again. Since the 
Operating System automatically disables an exception when its exception 
handler is entered (see DISABLE_EXCEP)^ the exception handler should 
explicitly re-enctole the exception before it returns to the process. 
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5.7.4 ihFOLEXCEP Exception Maragemenl System call 

INFO_EXCEP (Var ErrNupirlnteger; 

Var ExDep_NaniB:t_ex_namB; 
Var E>CDep_Status:t_ex_sts) 

ErrNum: Error indicator 

Excep_Naine: Name of exception 
Excep~Status: status of exception 

nNFO_EXCEP returns Information about the exception specified dy 
Excep_Name. The parameter Excep_Status is a record containing information 
about the exception. This record contains: 

t_ex_sts = RECORD (• exception status •) 

Ex_occurred_f:Boolean;(*«xceptlon occurred flag ») 
Ex_8tate:t_ex_state; (• exception status *) 

NuinjBxcep : Integer; («no. of exceptions queued ») 
Hdl_adr:Longadr; ("exception handler's address ») 
END; 

Once Ex_occunBd_f has been set to true, only a call to FLUSH_EXCEP can 
set it to false. 
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5.75 SIGNAL_EXCEP ExcepUon Managennenl System cai 

SIGNAL.EXCEP (Var EriNLM: Integer; 

Var ExDep_NaiiB:t_ex_naBe; 
var Excep_Data: tjBXjdata) 

ErrNum: Error Indicator 

Excep_nane: Name of exception to be sigialed 

Excep__Data: Information for exception handler 

A process can signal the occurrence of an exception by calling 
S1GNAL_EXCEP. The exception handler associated with ExDep_Name is 
entered. It Is passed Excep_Data. a data area containing information about 
the nature and cause of the exception. The structure of this information area 
is: 

array [0..slze_exdata] of Longint 

SIGNAL_EXCeP can be used for user-defined exceptions and for testing 
exception handlers ctefined to harKlle system-defined exceptions. 
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5.7.6 FLUSH_EXC3EP ExcepUon Management system Call 

FLUSH^EXCEP (Var ErrNUBi:Integer; 

Var Excep_Name:t_ex_name) 

ErrNuni: Error indicator 

Excep_Naine: Name of exception whose queue is flushed 

FLUSH_EXCEP Clears out the queue associated with the exception 
ExDep_Name and resets Its "exception occurred" flag. 
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5.8 Event Management System calls 

This section describes all the Operating System calls that pertain to event 
management A summary of all the operating System calls can be found in 
Appendix A. The following special types are used in event management calls: 

Pathnane = STRING[255]; 
T_ex_naiiie = STRIN6[16]; 
T_chn_sts = Record 

chn_type :chn_klnd; 
nuni_events : integer; 
open_recv : Integer; 
open_send : integer; 
ecjiame -.pathname; 
end; 
chnjcind = (leitjec^ calljec); 
T_iBitlist = Record 

length: integer; 

refnuni:array [0..10] of integer; 
end; 
P_r_eventblK = *r_eventdlk; 
R_eventl)lk = Record 

event_header : t_eheader; 
event_text : t_event_text; 
end; 
T_eheader = Record 

sendj)id : longint; 
event_type : longint; 
end; 
T_event_text = array [0..9] of longint; 
P_s_eventdlk = "sjeventblk; 
SjBventblk = T_event_text; 
TiinBstiBp_interval = Record 

sec: longint; 
msec :0. ,999; 
end; 
Tlme_rec = Record 

year: integer; 
day:1..366; 
hour: -23.. 23; 
minute: -59. .59; 
second :0.. 59; 
msec:0..999; 
end; 
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5.8.1 rvNKE_Eve^_CHN Event Management system Call 

riAKE_EVENT_CHN (Var ErrNura: Integer; 

Var Event_ChnJlanB:PathnamB) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

MAKE_EVENT_CHN creates an event channel with the name given in 
Event_Chn_Name. The name must be a File System pathname; It cannot de 
null. 
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5.8.2 KILL_EVENT_CHN Event Management System Call 

KILL_EVENT_CHN (Var ErrNuTO: Integer; 

Var Event_Chn_Name:PatnnamB) 

ErrNum: Error Indicator 

Event_Chn_Name: Pathname of event channel 

To delete an event channel, call KILL_EVENT_CHN. The actual deletion is 
delayed until all processes using the event channel have closed it. In the 
period between the KILL_EVENT_CHN call and the channel's actual deletion, 
no processes can open it. A channel can be deleted by any process that 
knows the channel's name. 
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5.8.3 OPEN_EVENT_CHN Event Management System Call 

OPEN_EVENT_CHN (Var ErrNumrlnteger; 

Var E vent_cnn_Name : Pathname; 
Var Refnum: Integer; 

ExcepName : tex name; 

Receiver : Boolean) 

ErrNum: Error indicator 

Event_Chn_Name : Pathname of event channel 
RefNum: Identifier of event channel 

Excep_Name: Exception name, if any 

Receiver: Access mode of calling process 

OPEN_EVENT_CHN opens an event channel and defines its attributes from the 
process point of view. RefTshjm is returned by the Operating System to be 
used in any further references to the channel. 

Event_Chn_Name determines whether the event channel is locally or globally 
defined. If it is a null string, the event channel is locally defined, if 
Event_Chn_Name is not null, it is the File System pathname of the channel. 

Excep_Name determines whether the channel is an event-wait or event-call 
channel. If it is a null string, the channel is of event-wait type. Otherwise, 
the channel is an event-call' channel and Excqp_Name is the name of the 
exception that is signaled when an event arrives in the channel. Excep_Name 
must be declared before its use in the OPEN_EVENT_CHN call. 

Receiver is a Boolean value indicating whether the process is opening the 
channel as a sender (Receiver is false) or a receiver (Receiver is true). A 
local Channel (one with a null pathname) can be opened only to receive 
events. Also, a call-type channel can only be opened as a receiver. 



5-20 



Operating System Reference Manual Exceptions and E\/ents 

5A4 CLOSE_EVEhfr_CHN Event Management System Call 

CL0SEJEVENT_CHN (Var ErrNum : Integer; 
RefNum: Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be closed 

CLOSE_EVENT_CHN Closes the event channel associated with RefNum. Any 
events queued in the channel remain there. The channel cannot be accessed 
until it is opened again. 

If the channel has previously been killed with KILLJEVENTjCHN^ you cannot 
open it after it has been closed. 

If the channel has not been killed, it can be opened by CPEN_EVENT_CHN. 
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5.8.5 INFO_EVENT_CHN Event Management System Call 

I^FO_EVENT_CHN (Var ErrNum: Integer; 
RefNura: Integer; 
Var cnn_Info:t_crin_sts) 

ErrNum: Error indicator 

RefNum: Identifier of event channel 

Chn_Info: Status of event channel 

INFO_EVENT_CHN gives a process information about an event channel. The 
Operating System returns a record, Chnjnfo, with information pertaining to 
the channel associated with ReflMum. 

The definition of the type of the Chnjnfo record is: 

t_chn_sts = 

RECORD (* event channel status *) 

Chn_type:Chn_klnd; (* «»ait_ec or call_ec *) 
l*jm_events: Integer; (* nunter of quet^ events *) 
Open_recv: Integer; (* number of processes reading channel *) 
Open_send: integer; (* no. of processes sending to this 

channel *) 
Ecjianie-.pathnane; (* event cheBviel name *) 
END; 
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5.8.6 WAIT_EVENT_CHN Event Management System Call 

IIAIT_EVENT_CHN (Var ErrNum: Integer; 

Var ialt_Llst:t_i»aitlist; 
Var RefNum : Integer; 

E vent_Ptr : p_r_eventblk ) 

ErrNum: Error indicator 

Wait_List: Record with array of event channel refnums 

RefNum; Identifier of channel that had an event 

Event_Ptr: Pointer to event data 

WAIT_EVENT_CHN puts the calling process In a waiting state pending the 
arrival of an event in one of the specified channels. Wait_List is a pointer to 
a list of event channel identifiers. When an event arrives in any of these 
channels^ the process is made ready to execute. RefNum identifies which 
channel got the event, and Event_Ptr points to the event itself. 

A process can wait for any Boolean combination of events, if it must wait 
for any event from a set of channels (an OR condition^ it should call 
WAIT_EVENT_CHN with WaitJLlst containing the list of event channel 
identifiers. If. on the other hand, it must wait for all the events from a set 
of channels (an AND condition), then for each channel in the set, 
WAIT_EVENT_CHN Should be called with WaitJ_ist containing just that 
channel identifier. 

The structure of t_waitlist is: 

RECORD 

Length: Integer; 

Refnuni:Array[0..size_i»altllst] of Integer; 
END; 

Event_Ptr is a pointer to a record containing the event header and the event 
text. Its definition is: 

P_r_eventblk = *r_eventDlk; 
R_eventl)lk = Record 

event_header : t_eheader; 

event_text : t_event_text; 
end; 
T_eheader = Record 

sendj)id : longlnt; 

event_type : longlnt; 
end; 
T_event_text = array [0. .9] of longint; 

Send_pld is the process id of the sender. 
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Currently^ the possible event type values are: 

1 - Event sent by user process 

2 - Event sent by system 

When you receive the SYS_SON_TERM event, the first longint of the event 
text contains the termination cause of the son process. The cause is same as 
that given in the sys_terminate exception given to the son process. The 
rest of the event text can be filled by the son process. 

If you call WAIT_EVENT_CHN on an event-call channel that has queued 
events, the event is treated just like an event in an event-wait channel. If 
WAIT_EVENT_CHN is called on an event-call channel that does not have any 
queued events, an error is returned. 
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5.8.7 FLUSH_EVENT_CHN Event Management System Call 

FLUSH_EVENT_CHN (Var ErrNum: Integer; 
Ref Nun: Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be flushed 

FLUSH_EVENT_CHN Clears out the specified event channel. All events 
queued in the channel are removed. If FLUSH_EVENT_CHN is called dy a 
sender^ it has no effect. 
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5.8.8 SENDJEVENT_CHN Event Management system call 

SEND_EVENT_CHN (Var ErrNuTO: Integer; 
RefNuni : Integer; 
Event_Ptr :p_s_eventblk; 
Interval : TlmBstinp_interval; 
Clktlme : Timerec ) 

ErrNum: Error indicator 

RefNum: Channel for event 

Event_Ptr: Pointer to event data 

Interval: Timer for event 

Clktime: Time data for event 

SEND_EVENT_CHN sends an event to the channel specified by RefNum. 
Event_Ptr points to the event that is to be sent. The event data area 
contains only the event text; the header is added by the system. 

If the event is of the event-wait type^ the event is queued. Otherwise the 
Operating System signals the corresponding exception for the process receiving 
the event. 

If the channel is opened by several senders^ the receiver can sort the events 
by the process identifier^ which the Operating System places in the event 
header. Alternatively, the senders can place predefined identifiers, which 
identify the sender, in the event text. 

The Interval parameter indicates whether the event is a timed event. 

NOTE 

Timed events will not be supported In future releases of the Operating 
System. The Interval and Clktime parameters will be ignored in future 
releases. If you want your software to be upward-compatible, always 
set both fields of the Interval parameter to zero. 



Timestmpjnteival is a record containing a second and a millisecond field. If 
both fields are 0, the event is sent immediately. If the second given is less 
than 0, the millisecond field is ignored and the Time_rec record is used. If 
the time in the Time_rec has already passed, the event is sent immediately. 
If the millisecond field is greater than 0, and the second field is greater than 
or equal to 0, the event is sent that number of seconds and milliseconds from 
the present 

A process can time out a request to another process by sending itself a timed 
event and then waiting for the arrival of either the timed event or an event 
indicating the request has been served. If the timed event is received first, 
the request has timed out A process can also time its own progress by 
periodically sending itself a timed event through an event-call event channel. 
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5.9 Clock System Calls 

This section describes all the Operating System calls that pertain to the clock. 
A summary of all the Operating System calls can be found in Appendix A 

The following special types are used in clock calls: 

Tiiiiestnp_interval = Record 

sec:longint; 
msec : 0. .999; 
end; 
Time_rec = Record 

year: integer; 
day:1..366; 
hour: -23.. 23; 
minute: -59.. 59; 
second :0.. 59; 
msec:0..999; 
end; 
Hour_range = -23.. 23 
Minute_range = -59. .59; 
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5.9.1 DELAY_TIME Clock System Call 

DELAY_nME (Var ErrNum: Integers- 
Interval : Timestnp_interval; 
Clktime : Timejrec) 

ErrNum: Error indicator 
Interval: Delay timer 
Clktime: Time information 

DELAY_TIME Stops execution of tne calling process for tne number of seconds 
and milliseconds specified in tne Interval record. If this time period is zero^ 
CELAYJTIME has no effect If the period is less than zero^ execution of the 
process is delayed until the time specified by Clktime. 
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332 GET_TIME Clock System Call 

GET_nME (Var ErrNumrlnteger; 

Var Sys_TiiiB:Tiine_rec) 

ErrNum: Error indicator 
Sys_Time: Time information 

GET_TIME returns the current system clock time In the record Sys_Tima The 
msec field of Sys_Time always contains a zero on return. 
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5.9.3 SET_L0CAL_TIME_DIFF Clock System call 

SET_LOCy«-_nME_DIFF (Var ErrNuTO: Integer; 

Hour : Hour_range; 
Minute : hlnute_range) 

ErrNum: Error indicator 

Hour: Number of hours difference from the system clock 

Minute: Number of minutes difference from the system clock 

SET_LOCAL_TIME_DIFF informs the Operating System of the difference in 
hours and minutes between the local time and the system clock. Hour and 
Minute can be negative. 
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5.9.4 C0NVERT_TIME Clock System call 

CONVERT_nr€ (Var ErrNum: Integer; 

Var Sys_Tlme:Tinie_rec; 
Var Local_TlHie:TiniB_rec; 
To_Sys: Boolean) 

ErrNum: Error indicator 

Sys_Time: System clock time 

Local_Tinie: Local time 

To_Sys: Direction of time conversion 

CONVERT_TIME converts between local time and system clock time. 

To_Sys is a Boolean value indicating in wnich direction the conversion is to 
go. If To_Sys is true^ the system takes the time data in Local_Time and puts 
the corresponding system time in Sys_Time. If To_Sys is false^ the system 
takes the time data in Sys_TIme and puts the corresponding local time In 
Local_Time. Both time data areas contain the year, month, day, hour, minute, 
second, and millisecond. 
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Configuration 



Every Lisa system is configured using the Preferences tool. Preferences 
places the configuration state of the system in a special part of the system's 
memory called poiameter memory. Every time parameter memory is 
changed/ a copy of the new data is made on the boot disk. If the contents 
of parameter memory are lost, this disk copy is automatically restored to 
parameter memory. 

Several calls are provided that allow programs to request information about 
the configuration of the system. 

6.1 Conriguratiwi System C^ls 

This section describes all the Operating System calls that pertain to 
configuration. A summary of all the Operating System calls can be found in 
Appendix A. Special data types used by configuration calls are defined along 
with the calls. 
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6.1.1 READ.PMEM Configuration System Call 

REflD_PMEM (Var Enthn: Integer; Var RfereciPMenftec) 

ErrNum : Error code 

PMrec: Contents of parameter memory 

READ_PMEM returns the contents of parameter memory in PMrec. The 
contents of R*4rec are not to be interpreted by the caller. This routine 
exists for the purpose of obtaining Fl^lrec so that PMrec can be passed to 
the other configuration procedures described in this chapter. 
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b.12. GETNXTCONFIG ConTiguration System Call 

GETNXTCONFIG (Var CrrNiiii.- Integer; 

Var NextEnt]:y:Longint; 
Var Pnrec.-PnenRec; 
Var Config:Confi^Dev) 

ErrNum: Error code 

NextEntry: Enumeration index 

PMrec: Contents of paremeter memory 

Config: Configuration entry 

GETWXTCCMsFIG is used to enumerate device configuration information. 
NextEntry = is passed by the caller to start the enumeration. After the 
first call to GETNXTCONFIG^ the caller passes the previously returned value 
of NextEmtiy on each subsequent call to GETNXTCCMsFIG. The Operating 
System updates the value of NextEntry v-'ith each call. The enumeration is 
done using the caller's copy of parametei* memory (obtained by calling 
REM)_PNEM) which is input in R4rec. Upon return from the procedure, 
Config holds the next configuration record that was extracted from the copy 
of parameter memory. EnrNun = 799 is returned when no more configuration 
entries are available. 

The Config record contains: 

pos: cdjDosition; 

nExtWordS: byte; (*number of valid ExtWords following*) 

ExtWordS: arr8y[1..3] of Integer; 

Driver ID: longint; 

DevName: e_nane; 

where cd_position = record 

slot, Chan, dev: byte 
end; 

The pos record of three bytes indicates the position of the device being 
described. CtevName is a character string representation of this position. 
The characteristics of the device can be obtained by calling LOOKUP and 
passing -DevName as input. Table 6-1 shows the device names, as well as 
the aliases, which may be substituted for DevNanne in any Operating System 
call. 
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Coftfigtareiion 











Table 6-1 












Device Names 




Slot Chan Dev 


DevName 


Alias 


DescriDtion 


1 








#1 


SLOTl 


Peripheral at slot 1 


1 


X 





#l#x 


SLOTlCHftNx 


at slot 1 channel x 


1 


X 


y 


#l#x*y 


SLOTlCHflNxDEVy 


at slot 1 channel x device y 


2 








«2 


SL0T2 


Peripheral at slot 2 


2 


X 





nifx 


SL0T2CHflNx 


at slot 2 channel x 


2 


X 


y 


#2#x#y 


SL0T2CHANxDEVy 


at slot 2 channel x device y 


3 








#3 


SL0T3 


Peripheral at slot 3 


3 


X 





#3*x 


SL0T3CHANX 


at slot 3 channel x 


3 


X 


y 


#3#x#y 


SL0T3CHftNxDEVy 


at slot 3 channel x device y 


10 


1 





#10#1 


RS232A 


Serial Port A 


10 


2 





#10#2 


F5232B 


Serial Port B 


11 








un 


PARftPORT 


Parallel Port 


12 








#12 


UPPER or PARAPORT 


Hard disk on Lisa 2/10 


13 








#13 


LOWER 


Sony Drive 


14 


1 





#14#1 


UPPER 


Upper Floppy on Lisa 1 


14 


2 





#14#2 


LOWER 


Lower Floppy on Lisa 1 


15 


1 





#15#1 


ALTCONSOLE 


Alternate Console 


15 


2 





#15#2 


MAINCONSOLE 


Nain Console 




ExtWcicxfei contains optional extension words 


. If the device is a printer. 




ExtWGrds[i] contains the following: 





RECORD 
prlnter^flag: boolean; 
default.flag: boolem; 
print erID: 14 bits 



0€h 






= tnje(l) ♦) 

true if it's the default pirinter*) 

unique printer ID: 

32 := Inageifriter / M DTP 

33 = Daisy Hheel Printer 
33 « Ink Jet Printer ♦) 



DrwarlD contains the unique driver ID: 

32 = Serial Cable 

33 = Parallel Cable 

34 = 2 Port Card 

35 = ProFile 

36 = Sony 

37 = Prian Card 

38 = Priam Disk 

39 « Archive Tape 

40 = Console 
42 s Modem A 
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6.13 MACH_INFO ConTigurstion System Call 

nflCH.INFD (Var EixNui: Integer; 

Var The_info:Minfo) 

ErrNuTO: Error code 

The_infO: Type of Lisa being used 

MACHJNFO returns an array, The_info, showing the CPU board, I/O board 
and memory board in use: 

iilnfo = REEQRD 

cpu_boarct io_boarit nen.size: longint 

E^P; 

cpu_board always returns 0. n^mjsize returns the number of bytes in 
memory, io.toard returns: 

= Lisa 1 

1 = Lisa 2/10 

2 = Lisa 2, Lisa 2/3, or Lisa 1 upgraded to use micro diskettes. 
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6.1.4 CARDS_EQUIPPED Configu^ion System Call 

Cf1RDS_E0UIPPED (Var Entiin: Integer; 

Var Ifi_Slot:Slot_arTay) 

ErrNum: Error code 

In_Slot: Identifies the types of cards configured 

CARDS_EQUIPPED returns an array showing the types of cards which are in 
the various card slots. 

The definition of Slc]t_8n'cy iS: 

slot_array = array [1..3] of integer; 

where the array values may contain: 

= no card present 
2 = 2-port parallel card 
5 = Priam card 
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6.13 OSBOOTVOL Conrigtjrd;ion System Call 

OSBOOTVOL (Var EnNiii: Integer; var VolNane: e.nane); 

ErrNum: Error code 

VolNarae: Identifies the device neme for the boot volume 

OS9900TVOL returns the device name of the boot volume. This port might 
not be the port configured for the boot volume, since it is possible for the 
user to override the default boot volume. Characteristics about the device 
can be obtained by calling LOOKUP and passing VoUslanw. 
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Appendix A 
Operating System Interface Unit 



UNIT syscall; 
INTRINSIC; 

INTERFACE 



(* system call definitions unit *) 



CONST 

iiiax_enanie = 32; (^ 

inaxjMtnnaine = 255; 

inax_label_size = 128; 

len_exnaRie = 16; 

sizejBXdata = 11; 



maxinuni length of a file system object name 
maximLm length of a file system pathname 
maximuin size of a file lately in bytes 
length of exception name 
48 bytes^ exception data block should have the 
same size as r eventblk^ received event block 



size_etext = 9; (* event text size - 40 bytes * 

size_»aitlist = 10; (* size of wait list - should be same as reqptr_list * 



(* exception kind 
call_term = 0; 
ended = 1; 
selfjcilled = 2; 
killed = 3; 
f thr_terra = 4; 
bad_syscall = 5; 
badermum = 6; 
sirap_error = 7; 
stkjDverf low = 8; 
datajDverf low = 9; 
parity_eiT = 10; 



definitions for •SYS_TERraNATE' exception 

* process called teniiinate_process 

* process executed 'end' statement 

* process called kill_process on self 

* process was killed by another process 

* process's father is terminating 

* process made invalid sys call - subcode bad 

* process passed bad address for ermum parm 

* process aborted due to code swap-in error 

* process exceeded max size (+T nnn) of stack 

* process tried to exceed max data space size 

* process got a parity error while executing 



def_div_zero = 11; (* default handler for div zero exception was called * 

def_value_oob = 12; (* " for value oob exception * 

defjovfw = 13; (* " for overflow exception * 

def_nrai_key = 14; (* " for NMI key exception * 

def_range = 15; (* " for 'SYSJ/ALUEjOOB* excep due to value range err * 

def_str_index = 16; (* " for •SYS_VALUE_OOB' excep due to string index err * 
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dusjBiTor = 21j 
addrjBrror = Zl; 
illgLlnst = 23; 
privj/iolatlon = 24; 
llne_1010 = 26; 
line_llll = 27; 

unexpected_ex = 29; 

dlv_zero = 31; 
value_oob = 32; 

OVf w - 33; 

nrnljcey = 34; 
value_range = 35; 
str Index = 36; 



(* 
(* 

( 



bus error occurred 
address error occurred 
illegal Instruction trap occurred 
privilege violation trap occurred 
line 1010 emulator occurred 



(« line 1111 emulator occurred 
(* an unexpected exception occurred 
(« exception kind definitions for hardware exception 



(* excep kind for value range and string index error 
(* Note that these tw cause 'SYS.VALUE.OOB' excep 



(«OEVICE_CGNTROL functions*) 



dvParlty = i; 
dvOutDTR = 2; 
dvOutXON = 3; 
dvOutOelay = 4; 
dvBaud = 5; 
dvimfait « 6; 
dVlnOTR = 7; 
dvInXON ' 8; 
dvTypeahd = 9; 
dvOiscon = 10; 
dvOutNoHS = 11; 
dvErrStat = 15; 
dvGetEvent = 16; 
dvAutoLF = 17; 
dvDlskStat = 20; 
dvOiskSpare = 21; 

TYPE 

pathname = string [max_pathname]; 
e_namB = string [maxjenarae]; 
namestring = string [20]; 
procinfoRec = record 
progpathname : pathname; 







*) 
*) 
*) 
-) 
*) 
*) 

-) 

*) 



«RS-232«) 

*RS-232») 

«RS-232») 

*RS-232*) 

«RS-232») 

*RS-232, CONSOLE^ 

«RS-232*) 

*RS-232«) 

*RS-232») 

*RS-232«) 

*RS-232«) 

•PROFILE*) 

•CONSOLE*) 

*RS-232, CONSOLE^ PARALLEL PRINTER*) (*not yet*) 

*DISKETTE. PROFILE*) 

-DISKETTE, PROFILE*) 



global_id 
father_id 
priority 
state 
data in 



longint; 
longint; 

1..255; 

(pactive, psuspended^ plaiting); 
txnlean 



end; 
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Tdstype = (ds_shared, cls_private); (* types of data segments *) 

dsinfoRec = record 

mein_slze : longint; 

disc_size: longint; 

mwtoopen : integer; 

Idsn : integer; 

boundF : boolean; 

presentF : boolean; 

creatorF : boolean; 

rwaccess : boolean; 

segptr : longint; 

volnanie: e_nanie; 
end; 



t_ex_name = string [len_exname]; 

longadr = "longint; 

t ex_state = (enabled, queued, ignored); 

pjex_data = "t_ex_data; 

t__ex_data = array [0..size_exdata] of longint; 

t_ex_.sts = record 

exoccurredf : boolean; 

ex_state : t ex state; 



num_excep : integer; 


hdl_adr 


: longadr; 


end; 




P_env_blk = '"env blk; 


env blk 


= record 


pc : 


longint; 


sr : 


integer; 


dO : 


longint; 


dl : 


longint; 


d2 : 


longint; 


d3 : 


longint; 


d4 : 


longint; 


d5 : 


longint; 


d6 : 


longint; 


d7 : 


Icwigint; 


aO : 


longint; 


al : 


longint; 


a2 : 


longint; 


a3 : 


longint; 


34 : 


longint; 


as : 


longint; 


a6 : 


longint; 


a7 : 


longint; 


end; 





(* exception name 
(* exception state 

{* exception data blk 

(* exception status 
(* exception occurred flag 
(» exertion state 
(* nunt)er of exceptions q'ed 
(* handler address 



(* environment block to pass to handler 

(* program counter 

(* status register 

(* data registers 0-7 



*) 
-) 
*) 
-) 
-) 



(* address registers 0-7 
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(* teimlnate exception data blcx)k 



p_tenn_ex_clata = *tenn_ex_clata; 
term_ex_data = record 

case excep_kind : longint of 

call_tenii 

ended^ 

self_killed. 

killed, 

fthr_terni 

bad_syscall, 

bad_ermunt 

si»ap_error, 

stk_overflow, 

data_overflo», 

parity_err : (); (* due to process termination 



lHQLlnst. 
priv_violation, 

line_1010, 

line_llll, 

def_div_zerOy 

def_value_oob, 

def_ovfw, 

def_nroi_key 



(* due to illegal instruction^ privilege 

violation *) 

(* due to line 1010, nil emulator *») 



end; 



(* terminate due to default handler for hardware 
exception *) 

: (sr : integer; 

pc : longint); (* at the time of occurrence *) 

def_range, 

def_str_index (* terminate due to default handler for 

'SYS_VALUE„OCe' excep for value range or string 
inctex error *) 

: (value_check : integer; 
upper_bound : integer; 
lower_bound : integer; 
return J3c : longint; 
caller_a6 : longint); 
bus_error, 

addr_error (* due to bus error or address error *) 
; (fun_field : packed record (* one integer *) 

filler : o..$7ff; (* 11 bits *) 

r_w_flag : boolean; 
i_n_flag : boolean; 
fun code : 0.,7; (* 3 bits «) 
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access_adr : longlnt; 
inst_register : integer; 
sr_error : Integer; 
pc_error : longint); 
end; 

p_hard_ex_data = '*hard_ex_data; 
hard_ex_data = record 

case excep_klnd : longlnt of 

div_zero, value_oob^ ovf •» 

: (sr : Integer; 

pc : longlnt); 

value_range, str_lndex 

: (value_cheok : Integer; 

upper_bound : Integer; 

loi»er_bound : Integer; 

return jx) : longlnt; 

caller_a6 : longlnt); 
end; 



(« hardware exception data block 



accesses = (dreads dwrite^ append^ private, glor)al_refnuin); 

mset = set of accesses; 

lomode = (absolute, relative, sequential); 

UID = record (^unique id*) 

a,b: longlnt 
end; 



tiinestrap_interval = record 

sec : longint; 

msec : 0..999; 
end; 



(* time interval *) 

(* number of seconds *) 

(* number of milliseconds within a second *) 



info_type = (devlce_t, volurae_t, object_t); 

devtype = (diskdev, pascalbd, seqdev, bitbkt, non_io); 

filetype = (undefined, MDOFflle, rootcat, freellst, badblocks, sysdata, 

spool, exec, usercat, pipe, bootf lie, svapdata, swapcode, ramap, 

userflle, killedobject); 

entrytype= (enptyentry, catentry, llnkentry, flleentry, plpeentry, ecentry, 
killedentry); 
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f s_lnfo = record 
name : e_name; 
dlrjatn : pathname; 
machlne_id : longint; 
f sjovemead : integer; 
result_scavenge : Integer; 
case otype : info_type of 
device_t^ volume_t: ( 
iochannel : Integer; 
devt : devtype; 
slot_no : integer; 
fs_size : longint; 
vol_slze : longint; 
blockstructured, mounted : boolean; 
opencount : longint; 

privatedev, remote^ lockeddev : boolean; 
motmtjpendlng, unraount_pendlng : boolean; 
volname^ password : e_name; 
f sversion, volnuro : Integer; 
VOlid : UID; 
backup_volid : UID; 

blocksize, datasize, clustersize^ filecount : Integer; 
label_sl2e : integer; 
f reecount : longint; 
OTVC. DTCC. D7VB, OTVS : longint; 
master_copy_ld, copy_tnread : longint; 
ovenK)unt_stanp : UID; 
boot_code : integer; 
boot_environ : integer; 
privileged^ write jarotected : boolean; 
master, copy, copy_f lag, scavenge_f lag : boolean; 
vol_left_mounted : boolean ); 

obJect_t : ( 

size : longint; 

pslze : longint; (* physical file size in bytes *) 

ipslze : integer; (* logical page size In bytes for this file *) 

ftype : filetype; 

etype : entrytype; 

DTD, DTA, DTTt DTB, DTS : longint; 

ref num : Integer; 

f mark : longint; 

acmode : mset; 

nreaders^ nwriters, nusers : integer; 

fuid : UID; 

user_type : integer; 

user_subtype : Integer; 
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system_type : Integer; 
eof, safety_on, kswltch : boolean; 
private^ locked, protected, master_flle : boolean; 
file_scavenged, file_closed_by_OS, file_left_open: boolean) 
end; 

dctype = record 

dcversion : integer; 

decode : integer; 

dcdata : array [0..9] of longint; 
end; 



t_i»aitlist = record 

length : integer; 

refnum : array [0..slze_i»aitlist] of integer; 
end; 



(* user/driver defined data 



(* wait list 



t_eheader = record 

send_pid : longint; 
event_type : longint; 

end; 



(* event header 

(* sender's process id 

(* type of event 



t_event_text = array [0..size_etext] of longint; 
p_r_eventblk = "r_ev/entblk; 
r_eventDlk = record 

event_header : t_eheader; 

event_text : t_event_text; 
end; 

p_s_eventblk = "s_eventblk; 
s eventblk = t event text; 



tinie_rec = record 

year : integer; 

day : 1..366; 

hour : -25. .23; 

minute : -59.. 59; 

second : 0..59; 

msec : 0..999; 
end; 



(* Julian date *) 
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cf¥i_klnd = (i«lt_ec^ calljec); 
t_crin_sts = record 

chn_type : cf¥>_kln(f 

nurojBvents : integer; 

open_recv : integer; 

open_send : integer; 

ecjeme : patrname; 
end; 

hourjrange = -23. .23; 
mlnute_range = -59. .59; 



(• channel status *) 

(• channel type 

(« nunter of events queued 

(* nunCer of opens for receiving 

(« nuRtier of opens for sending 

(* event channel name 



{configuration stuff: } 

tports ^ (uppertwlg, lovertvig, parallel, 
slotll. slotl2, slotl3, slotl4, 

Slot21, SlOt22, SlOt23, Sl0t24, 
SlOt3L SlOt32, Sl0t33, Sl0t34, 

seriala, seriald, iBain_console, altjconsole, 
tjBouse, t_speaker, tjextraL t_extra2, t_extra3); 

card_types = (no_cant apple_card, njwrtjcant net_cant laserjcard); 

slotjarray = array [1..3] of card_types; 

{ Lisa Office System parameter meinory type } 

pneyteUhique = -128,. 127; 

pflenftec = array [1.. 62] of pneyteUhique; 

(* File System calls *) 

procedure MftKE_FILE (var ecode: Integer; var path: pathname; 
label_size : integer); 

procedure MAKE_PIPE (var ecodeilnteger; var path:pathnaiiie; 
label_size : integer); 

procedure HAKE_CATALOG (var ecode: integer; var path: pathname; 
label_size : integer); 

procedure riAKE.LINK (var ecode: integer; var path, ref :pathname; 
label_size : integer); 
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procechjre KILL_C»JECT (var ecode: Integer; var path: pathname); 

procedure UNKILL_FILE (var ecode: Integer; refnum: integer; var 
new_name : enane); 

procedure OPEN (var ecode: integer; var path: pathname; var refrnm: integer; 
n)anlp:niset); 

procedure CLOSE_OBJECT (var ecode: integer; refnum: integer); 

procedure READ_DATA (var ecode: integer; refnum: integer; data_addr:longint; 
c(Xflit:lof^int; var actual :lmgint; mode:iomode; 
offset :longint); 

procedure »RITE_DATA (var ecode:integer; refnumcinteger; data_addr:longint; 
count:lmgint; var actual:longint; mode:icMnode; 
offset:longint); 

procedure flush (var ecode: integer; refnum: integer); 

procedure LOOKUP (var ecode:integer; var path:pathname; var 
attributes:fs_info); 

procedure INFO (var ecode: integer; refnum: integer; var refinfo:fs_info); 

procedure ALLCKJATE (var ecode:integer; refrxmtinte^r; contiguous:boolean; 
count:longint; var actual:longint); 



procedure TRUNCATE (var ecode:integer; refnum:integer); 

procedure COMPACT (var ecode:integer; refnumcinteger); 

procedure RENAnE_ENTRY ( var ecode: integer; var path: pathname; var 
newTame:e_nane ); 

procedure f^ADLABEL ( var ecode: integer; var path:patf¥iame; 

data_addr:longint; count:iongint; var actual:longint ); 

procedure «»RITE_LABEL ( var ecode: integer; var patmpathname; 

dataaddr.longint; count:lor^int; var actual:longint ); 

procedure MOUNT ( var ecode: integer; var vnane : encme; var password : 
e_name ;var devname : e_name); 

procedure UNMOUNT ( var ecode: integer; var vname : e_name ); 
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procedure SETJilORKING_DIR ( var ecode : integer; var path: pathname ); 

procedure ^TJKH<irc_DIR ( var ecode: integer; var path: pathname ); 

procedure SETSAFETY (var ecode: integer; var path: pathname; onoff: boolean ); 

procedure DEVKJECONTROL ( var ecode: integer; var path:patrv)ane; 
var cparm : dctype ); 

procedure RESET_CATALOG (var ecode: integer; var path:patr)naiiie); 

procedure get_next_ENTRY (var ecode: integer; var prefix, entry:e..name); 

procedure SET_FILE_INFO (var ecode :integer; refnum: integer; fsi:fs_info); 

(* Process hanagement system calls *) 

function tty_ID;longlnt; 

procedure Info_Process (var ermuntlnteger; proc_id:longlnt; var 
proc_info:procinfoRec); 

procedure Yield_CPU (var errrMit integer; to_my:boole^); 

procedure SetPriority_Process (var errntan: integer; proc_id:longint; 
new_priorlty:lnteger); 

procedure Suspend_Process (var er mum: integer; proc_id:longint; 
suspf ani ly:booleai ) ; 

procedure ActivateProcess (var errmm: integer; proc_id:longint; 
act_f ami ly:boolean); 

procedure Kili_Process (var errniMlnteger; proc_ld:longint); 

procedure Termlnate_Process (var errnum: integer; event jDtr:p_s_eventblk); 

procedure M^e_Pr(X5ess (var errnunt integer; var prc»_id:lmgint; var 
progfile:patlnane; var entrynane:namestring; 
e vnt_chn_ref FMit integer ) ; 
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(* Memory hanagement system calls *) 

procedure inake_clataseg(var errnum: integer; var segname: pathname; mem_size, 
disc size: icngint; var refnum: integer; var seg)tr: 
longint; Idsn: integer; dstype: Tdstype); 

procedure kiil_dataseg (var ermum: integer; var segnamerpathnawe); 

procedure c^Den_dataseg (var ermum: integer; var segname:pathname; var 
refnum: integer; var segptr:longint; idsntinteger); 

procedure closedataseg (var errnum:integer; refnum:integer); 

procedure size_dataseg (var errnijm: integer; refnum: inte^r; 

deltamemsize:longint; var r«2wmemsize:longint; 
deltadiscsize: longint; var newdiscsize: longint); 

procedure info_dataseg (var errnum: integer; refnumrinteger; var 
dsinf o:dsinf oRec ); 

procedure setaccess_dataseg (var errnum: integer; refruHitinteger; 
readonly:t)oolean); 

procedure unbinddataseg (var errrMitinteger; refnum:integer); 

procedure Dind_dataseg(var errnurrtinteger; refnum:integer); 

procedure info Idsn (var ermum:integer; Idsn: integer; var refnum: integer); 

procedure flush dataseg( var errnum: integer; refrMn: Integer); 

procedure mem_info(var errnum: integer; var swapspace. dataspace, 
cur_codesize^ maxcodesize : icngint); 

procedure info_address(var errnum: integer; address: longint; var refnum: 
integer); 

(* Exception Management system calls *) 

procecfcjre declare_excep_hdl (var ermujit integer; var excepnane-.texnane; 
entry_point:longadr ); 

procedure dlsable_excep (var errnum: integer; var excep_name:t_ex_name; 
queue:boolean); 
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procedure enable_excep (var ermuntlnteger; var excep_name:t_ex_name); 

procedure slgnal_excep (var ermuntlnteger; var excep_nafne:t_ex_nanie; 
excep_data:t_ex_data); 

procedure info_excep (var ermuntinteger; var excep_nanie:t_ex_name; var 
excep_status:t_ex_sts); 

procedure flush_excep (var errnuc?tinteger; var excep_name:t_ex_name); 

(* Event Channel management system calls *) 

procedure make_event_chn (var ermumrinteger; var event_chn_naroe:pathname); 

procedure kill_event_chn (var errnumclnteger; var event_chn_name:pathname); 

procedure q[)en_event_cnn (var errnumclnteger; var event_chn_name:patnnane; var 
refnumrinteger; var excep_name:t_ex_name; 
receiver:boolean); 

procedure close_event_cnn (var ermumrinteger; refnum:integer); 

procedure info_event_chn (var errnumclnteger; refnum:integer; var 
chn_lnfo:t_cnn_sts); 

procedure «ait_event_chn (var ermuntlnteger; var walt_list:t_waitlist; var 
refnunt Integer; event _ptr:p_r_eventblk); 

procedure flush_event_cnn (var ermuntlnteger; refnuntlnteger); 

procedure send_event_cnn (var ermuntlnteger; refnuntlnteger; 

event_ptr:p_s_eventDlk; lnterval:tlmestnp_lnterval; 
clktime:tlme_rec); 



(» Timer functions system calls *) 

procedure delaytlme (var ermuntlnteger; lnterval:tlmestnp_lnterval; 
clktlme:tlme_rec); 

procedure get_tlme (var ermuntlnteger; var gmt_time:tlme_rec); 

procedure set_iocal_tlme_dlff (var ermuntlnteger; hour:hour_range; 
mlrKJte:mlnute_ range); 
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procedure convert_tlme (var ermuntlnteger; var gmt_tlme:tlme_rec; var 
local_time:time_rec; tojgmt:tX)Olean); 

{configuration stuff} 

function OSBCX)TVOL(var error : integer) : tports; 

procedure GET_CCM'IG_NAME( var error: integer; devpostn:tports; var 
devnamB:e_name); 

procedure CARDS_EOUIPPED(var errorrinteger; var in_slot:slot_array); 

IMPLEMENTATION 

procedure M/y<E_FlLE; external; 
procedure MAKE_PIPE; external; 
procedure MAKE_c/\TAl_OG; external; 
procedure MAKEJJNK; external; 
procedure KILL_OBJECT; external; 
procedure OPEN; external; 
procedure CLOSE_OBJECT; external; 
procedure READ_DATA; external; 
procedure WRITE_DATA; external; 
procedure FLUSH; external; 
procedure LOOKUP; external; 
procedure INFO; external; 
procedure ALLOCATE; external; 
procedure TRUNCATE; external; 
procedure COMPACT; external; 
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procedure RENAME_ENTRY; external; 
procedure READ_LABEL; external; 
procedure «IRITE_LABEL; external; 
procedure MOUNT; external; 
procedure UNMOUNT; external; 
procedure SET_IWRKING_DIR; external; 
procedure GET_iORKING_DIR; external; 
procedure SET_SAFETY; external; 
procedure DEVICE_CONTROL; external; 
procedure RESET_CATALOG; external; 
procedure GET_NEXT_ENTRY; external; 
procedure GET_OEV_NAME; external; 

function My_ID; external; 
procedure Inf o_Process; external; 
procedure Yield_CPU; external; 
procedure SetPriority_Process; external; 
procedure SuspendProcess; external; 
procedure ActivateProcess; external; 
procedure KillProcess; external; 
procedure Terndnate_Process; external; 
procedure MakeProcess; external; 
procedure Sched_Class; external; 
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procedure make_dataseg; external; 
procedure kill_dataseg; external; 
procedure open_dataseg; external; 
procedure close_dataseg; external; 
procedure slze_dataseg; external; 
procedure inf ojdataseg; external; 
procedure setaccess_dataseg; external; 
procedure unbind_dataseg; external; 
procedure blnd_dataseg; external; 
procedure inf o_ldsn; external; 
procedure f lusn_dataseg; external; 
procedure inein_lnf o; external; 

procedure declare_excep_hdl; external; 
procedure dlsable_excep; external; 
procedure enable_excep; external; 
procedure slgnal_excep; external; 
procedure lnfo_excep; external; 
procedure f lush_excep; external; 

procedure raake_event_chn; external; 
procedure kill_event_chn; external; 
procedure open_event_chn; external; 
procedure close_event_chn; external; 
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procedure lnfo_event_chrv extemaL* 
procedure iait_event_chn; external; 
procedure f lush_event_cnn; external; 
procedure send_event_cnn; extemaL- 

procedure delay_tlmB; external; 
procedure get_timB; external; 
procedure set_local_timB_diff; external; 
procedure convert_tiine; external; 
procedure set_f ile_info; external; 
function ENAa.EDBG; external; 
function OS800TVOL; external; 
procedure GET_t»NFlG_NAME; external; 
function DISK_LIKELY; external; 
procedure CARDS_EQUIPPED; external; 
procedure Read_Pt1enu external; 
procedure «»rite_PMeiiu external; 
end. 
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SYS OVERFLOW 



Overflow exception. Signaled when the TRAPV instruction is 
executed and the overflow condition is on. 



SYS WfiLUE 0GB 



Value-out-of-bomd exception. Signaled when the CHK 
instruction is executed and the value is less than or greater 
than upper bound. 



SYS_ZERO_DIV Division by zero exception Signaled when the DIVS or DIVU 
instruction is executed and the divisor is zero. 

SYS_TERMINATE Termination exception. Signaled when a process is to be 
terminated. 



B-1 



Appendix C 

System-Reserved 

Event Types 



SYS_SON_TERM "Son terminate" event type. If a father process has created a son 
process with a local event channel, this event Is sent to the 
father process when the son process terminates. 
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Appendix D 
Error Messages 



-6081 End of exec file input 

-6004 Attempt to reset text file with typed-f ile type 

-6003 Attempt to reset nontext file with text type 

- 1885 ProFile not present during driver initialization 

- 1882 ProFile not present during driver initialization 

-1840 Packet ended in aresumable state (Archive). 

- 1293 Object is not password protected. 

-1176 Data in the object have been altered by Scavenger 

-1175 File or volume was scavenged 

-1174 File was left open or volume was left mounted, and system crashed 

-1173 File was last closed by the OS 

- 1 146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent boot 

volume 
-1060 Attempt to mount a foreign boot disk following a temporary unmount 
- 1059 The bad block directory of the diskette is almost full or difficult to read 
-696 Printer out of paper during initialization 
-660 Cable disconnected during ProFile initialization 
-626 Sc»/enger indicated data are questionable, but may be OK 
-622 Parameter memory and the disk copy were both invalid 
-621 Parameter memoary was invalid but the disk copy was valid 
-620 Parameter memory was valid but the disk copy was invalid 
-413 Event channel was scavenged 
-412 Event channel was left open and system crashed 
-321 Datasegment open when the system crashed. Data possibly invalid. 
-320 Could not determine size of data segment 
-150 Process was created, but a library used by program has been scavenged and 

altered 
-149 Process was created, but the specified program file has been scavenged aaid 

altered 
-125 Specified process is already terminating 
-120 Specified process is already active 
-115 Specified process is already suspended 

100 Specified process does not exist 

101 Specified process is a system process 

1 10 Invalid priority specified (must be 1..225) 

130 Could not open program file 

131 File System error while trying to read pro-am file 

132 Invalid program file (incmrrect format) 

133 Could not get astack segment for new process 

134 Could not get asyslocal segment fen- new process 
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135 Could not get sysglobal space for new process 

136 Could not set up communication channel for new process 
138 Error accessing program file while loading 

141 Error accessing a library file while loading program 

142 Cannot run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic Library 

144 Program uses an intrinsic unit whose name/type does not agree with the 
Intrinsic Library 

145 Program uses a shared segment not found in the Intrinsic Library 

146 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

147 No space in syslocal for program file descriptor during process creation 

148 No space in the shared lU data segment for the program's shared lU globals 

190 No space in syslocal for program file description during List_LibFiles 
operation 

191 Could not open program file 

192 Error trying to read program file 

193 Cannot read protected program file 

194 Invalid program file (incorrect format) 

195 Program uses a shared segment not found in the Intrinsic Library 

196 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

198 Disk I/O error trying to read the intrinsic unit directory 

199 Specified library file number does not exist in the Intrinsic Library 

201 No such exception name declared 

202 No space left in the system data area for Declare_Excep_Hdl or 
Signal_Excep 

203 Null name specified as exception name 

302 Invalid LDSN 

303 No datasegment bound to the LDSN 

304 Data segment already bound to the LDSN 

306 Data segment too large 

307 Input data segment path name is invalid 

308 Datasegment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified 

311 Insufficient system resources 

312 Unexpected File System error 

313 Data segment not found 

314 Invalid address passed to Info_Address 

3 15 Insufficient memory for operation 

3 17 Disk error while trying to swap in data segment 

401 Invalid event channel name passed to Make_Event_Chn 

402 No space left in system global data area for Open_Event_Chn 

403 No space left in system local data area for Open_Event_Chn 

404 Non-block-structured device specified in pathname 

405 Catalog is full in Make_Event_Chn or Open_Event_Chn 
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406 No such event channel ex ists in Kill_Event_Chn 

4 10 Attempt to open a local event channel to send 

411 Attempt to open event channel to receive when event channel has a receiver 
4 13 Unex pected File System error in Open_Event_Chn 

4 16 Cannot get enough disk space for event channel in Open_Event_Chn 

417 Unex pected Fi le System err or in Close_Event_Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 Wait_Event_Chn returns empty because sender process could not complete 

422 Attempt to call Wait_Event_Chn on an empty event-call channel 

423 Cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of expected 
size 

425 Event channel empty after being unblocked, Wait_Event_Chn 

426 Bad request pointer error returned in Wait_Event_Chn 

427 Wait_List has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected File System error in Wait_Event_Chn 

430 Attempt to send to a channel which the calling process does not heve open 

431 Amount of data transferred while writing to event channel not of expected 
size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unex pected File System error in Send_Event_Chn 

440 Unexpected File System arror in MakelEventlChn 

44 1 Event channel already ex ists in Make_Event_Chn 
445 Unex pected File System error in KilLEvent_Chn 
450 Unex pected File System error in Flush_Event_Chn 

530 Size of stack expansion request exceed limit specified for program 

531 Cannot perform explicit stack expansion due to lack of memory 

532 Insufficient disk space for explicit stack expansion 
6(X) Attempt to perform I/O operation on non 1/0 request 
602 No more aleorms available dtffing driver initialization 

605 Call to nonconf igured device driver 

606 Cannot find sector on floppy diskette (disk unformatted) 

608 Illegal length or disk adcbress for tradisf er 

609 Call to nonconf igured device driver 

6 10 No more room in sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled on floppy 
drive 

614 No disk present in drive 

6 15 V«Arong call version to floppy drive 

6 16 Unpermitted floppy (frive function 

6 17 Checksum error on floppy diskette 

6 18 Cannot format, or write protected, or error unclamping floppy diskette 

619 No more room in sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 

625 Scavenger indicated data are bad 
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630 The time passed to Del8y_Time, Convert_Time, or Sencl_Event_Chn has 
invalid year 

631 Illegal timeout request parameter 

632 No memory availsJale to initialize clock 

634 Illegal timed event id of -1 

635 Process got unblocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to Delay_Time or Send_Event_Chn more than 23 datys from 
current time 

639 Illegal date passed to Set_Time, or illegal date from system clock in 
Get_Time 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write initiated with illegal parameter 

642 Unimplemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 Unexpected RS-232 timer interrupt 

648 Unpermitted RS-232 initialization, or disconnect detected 

649 Illegal device control parameters to RS-232 

652 N-port driver not initialized prior to ProFile 

653 No room in sysglobal to initialize ProFile 

654 Hard error static returned from chrive 

655 Wrong call version to ProFile 

656 Unpermitted ProFile function 

657 Illegal device control parameter to ProFile 

658 Premature end of file when reading from driver 

659 Corrupt File System header chain found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to ProFile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

670 Bad command response from drive 

671 Illegal length specified (must = 1 on input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 

675 Illegal device control 

680 Wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysglobal to initialize serial driver 

685 Eject not allowed this device 

686 No room in sysglobal to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 Wrong call version to n-port card driver 

690 Wrong call version to pearallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysglobal to initialize parallel printer 
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694 Unimplemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 

698 Printer off line 

699 No response from printer 

700 Mismatch between loader version number and Operating System version 
number 

701 OS exhausted its internal space during startup 

702 Cannot make system process 

703 Cannot kill pseudo-outer process 

704 Cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the File System volume 

708 Hard disk mount table unreadable 

709 Cannot map screen data 

7 10 Too many slot-based devices 

724 The boot tracks do not know the right File System version 

725 Either damaged File System or damaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM.OS is missing 

729 SYSTEM.CONFIG is corrupt 

730 SYSTEM.OS is corrupt 

731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

732 SYSTEM.LLD is corrupt 

733 Loader range error 

734 Wrong driver is found. For instance, storing a diskette loader on a ProFile 

735 SYSTEM.LLD is missing 

736 SYSTEM.UNPACK is missing 

737 Unpack of SYSTEM.OS with SYSTEM.UNPACK failed 

750 Position specified is out of range. 

751 No device exists at the requested position. 

752 Can't perform requested function while device is busy. 

753 Specified position is not a terminal node. 

754 Built-in devices cannot be configured. 

755 Isolated positions cannot be conf igiared. 

756 The specified position is already configured. 

757 Parallel Port doesn't exist on this type of machine. 

758 No room in memory for more devices. 

790 Can't get buffer space to load configurable dr iver. 

791 Configurable driver code file is not executable. 

792 Can't get memory space for a configurable driver . 

793 I/O error reading configurable driver file. 

794 Configurable driver code file not found. 

795 Configurable driver has more than one segment. 

801 lOResultoO on I/O using the Monitor 

802 Asynchronous I/O request not completed successfully 
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803 Bad combination of mode parameters 

806 Page specified is out of range 

809 Invalid arguments (page, address, offset, or count) 

8 10 The requested page could not be read in 

8 15 Not enough sysglobal space for File System buffers 

8 19 Bad device number 

820 No space in sysglobal for 8syncPtt"onous request list 

821 Already initialized I/O for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 
835 Invalids-file number 

837 Unallocsted s-f ile or I/O error 

838 Map overflow: s-f ile too large 

839 Attempt to compact file past PEOF 

840 The allocation map of this file is truncated. 

841 Unallocated s~f ile or I/O error 

843 Requested ex act f it^ but one could not be provided 

847 Requested transfer count is <= 

848 End of file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number 

854 No free slots in s-list directory (too many s-f iles) 

855 No available disk space for file hints 

856 Device not mounted 

857 Empty, locked, or invalid s-f ile 

861 Relative page is beyond PEOF (bad parameter value) 

864 No sysglobal space f cnr volume bitmap 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number 

868 Bad unit number 

869 Unit already mounted (mount)/no unit mounted 

870 No sysglobal space for DCB or MDDF 

871 Parameter not a valid s-f ile ID 

872 No sysglobal space for s-file control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 Invalid s-file ID or s-file control block 
879 Attempt to postion past LEOF 

881 Attempt to read empty file 

882 No space on volume for new data page of file 

883 Attempttoread past LEOF 

884 Not first auto-allocation, but file was empty 

885 Could not update f ilesize hints after a write 

886 No syslocal space for I/O request list 
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887 Catalog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry by that name already exists 

891 Catalog is full or is damaged 

892 Illegal name for an entry 

894 Entry not founds or catalog is damaged 

895 Inv/alid entry name 

896 Safety switch is on—cannot kill entry 

897 Invalid bootdevvalue 

899 Mtempt to allocate a pipe 

900 Invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device 

922 Invalid label size 

926 Pathname invalid or no such device 

927 Invalid label size 

94 1 Pathname invalid or no such device 

944 Object is not a file 

945 File is not in the killed state 

946 Pathname invalid or no such device 

947 Not enough space in syslocal for File System ref db 

948 Entry not found in specified catalog 

949 Private access not allowed if file already open shared 

950 Pipe already in use^ requested access not possible or dwrite not allowed 

951 File is already opened in private mode 

952 Badrefnum 

954 Badrefnum 

955 Read access not allowed to specified object 

956 Attempt to position FM ARK past LEOF not allowed 

957 Negative request count is illegal 

958 Nonsequential access is not allowed 

959 System resources exhausted 

960 Error writing to pipe while an unsatisfied read was pending 

961 Badrefnum 

962 No WRITE or APPEND access allowed 

963 Attempt to position FM ARK too far past LEOF 

964 Append access not allowed in absolute mode 

965 Append access not allowed in relative mode 

966 Internal inconsistency of FM ARK and LEOF (warning) 

967 Nonsequential access is not allowed 

968 Badrefnum 

97 1 Pathname invalid or no such device 

972 Entry not found in specified catalog 
974 Badrefnum 

977 Badrefnum 

978 Page count is nonpositive 

979 Not a block-structured device 
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981 Badrefnum 

982 No space has been allocated f cxr specified file 

983 Not a block-structured device 

985 Badrefnum 

986 No space has been allocated for specified file 

987 Not a block-structured device 

988 Badrefnum 

989 Caller is not a reader of the pipe 

990 Not a block-structured device 

994 Invalid refnum 

995 Not a block-structured device 

999 Asynchronous read was unblocked before it was satisfied 

1002 Invalid Device_Control call for device (Priam). 

1003 Unable to get Sy^Global space for disk operation (Priam). 

102 1 Pathname invalid or no such entry 

1022 No such entry found 

1023 Invalid newname, check for '-' in string 

1024 New name already exists in catalog 

1031 Pathname invalid or no such entry 

1032 Invalid transfer count 

1033 No such entry found 

104 1 Pathname invalid or no such entry 

1042 Invalid transfer count 

1043 No such entry found 

1051 No device or volume by that name 

1052 A volume is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume just unmounted from 
this Lisa 

1054 The bad block directory of the diskette is invalid 

106 1 No device or volume by that name 

1062 No volume is mounted on device 

1071 Not a valid or mounted volume for working directc»ry 

109 1 Pathname invalid or no such entry 

1092 No such entry found 
1101 Invalid device name 

1121 Invalid device^ not mounted, or catalog is damaged 

1122 No space for catalog scan buffer (Reset_Catalog). 
1 124 No space for catalog scan buffer (Get_Next_Entry). 
1128 Invalid pathname, device, or volume not mounted 

1130 File is protected; cannot open due to protection violation 

1131 No device or volume by that name 

1132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space in sysglobal for open file list 

1135 Cannot find the open file entry to modify 

1 136 Boot volume not mounted 

1137 Boot volume already unmounted 
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1138 Caller cannot have higher priority than system processes when calling ubd 

1141 Boot volume was not unmounted when cabling rbd 

1142 Some other volume still mounted on the boot device when calling rbd 

1143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted boot 
volume 

1145 No sysglobal space for bit map to do rbd 

1158 Track-by-track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 

1163 Illegal command 

1164 Device is not a diskette device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1 167 Not a block-structured device 

1168 Device name is invalid 

1169 Could not access device before initialization using default device 
parameters 

1170 Could not mount volume after initialization 

1171 '-'is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 

1176 Cannot read from a pipe more than half of its allocated physical size 

1177 Cannot cancel aread request for a pipe 

1178 Process waiting for pipe data got unblocked because last pipe writer closed 
it 

1180 Cannot write to a pipe more than half of its allocated physical size 

1181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was seiisf ied 

1183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unblocked because the reader closed the 
pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 
1188 Cannot compact a pipe while it has data wrapped around 

1 190 Attempt to access a page that is not allocated to the pipe 

1191 Bad parameter 

1193 Premature end of file encountered 

1196 Something is still open on device—cannot unmount 

1197 Volume is not formatted or cannot be read 

1198 Negative request count is illegal 

1199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 
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1210 Boot track program not executable 

121 1 Boot track program too big 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Boot track program file not found 

1215 Cannot write boot tracks on that device 

1216 Could not create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Could not find configuration information entry 

1219 Could not get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scewenger has detected an internal inconsistency symptomatic of a software 
bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1230 Cannot write consistently to the volume 

1231 Cannot allocate space (Heap segment) 

1232 Cannot allocate space (Map segment) 

1233 Cannot allocate space (SFDB segment) 
1237 Errcar rebuilding the volume root directory 

1240 Illegal attempt to scavenge a non-OS-formatted volume 

1281 Pathname is invalid because device or object is not present. 

1282 Pathname syntax is invalid. 

1283 Interior pathname component does ncA specify a directory object. 

1284 Directory cannot be deleted because it is not empty. 

1285 Operation is not allowed on avolume with aflat catalog. 

1286 Operation is not allowed on a directory object. 

1287 Cannot allocete SysLocal space for the directory scan stack. 

1288 Directory tree is inconsistent. 

1289 Operation not allowed against avolume or device (Quick_Lookup) 

1290 The directory that contained the file has been deleted (Unkill_File) 

1294 Supplied password does not match the password on the object. 

1295 The allocation map of this file is damaged and cannot be read. 

1296 Bad string argument has been passed 

1297 En^ name for the object is invalid (on the volume) 

1298 S-list entry for the object is invalid (on the volume) 
1907 No disk in floppy drive 

1820 Write-protect error on floppy drive 

1822 Unable to clamp floppy drive 

1824 Floppy drive write error 

1840 Unable to initialize disk drive (Priam). 

184 1 Error writing to disk (Priam) / Error reading from tape (Archive). 

1842 Error reading from disk (Priam) / Error writing to tape (Archive). 



D-10 



Qpesnsiing S^^em Reference Manual Error Messages 

1843 Error controlling tape (Archive). 

1844 Packet ended in a non-r esumable state (Archive). 

1845 Packet command had an error (Archive). 
1882 Bad response from ProFile 

1885 ProFile timeout error 

1998 Invalid parameter address 

1999 Badrefnum 

6001 Attempt to access unopened file 

6002 Attempt to reopen a file which is not closed using an open FIB (file info block) 

6003 Operation incompatible with access mode with which file was opened 

6004 Printer off line 

6005 File record type incompatible with character device (must be byte sized) 

6006 Bad integer (read) 

60 10 Operation incompatible with file type or access mode 

6081 Premature end of exec file 

6082 Invalid exec (temporary) file name 

6083 Attempt to set prefix with null name 

6090 Attempt to move console with exec or output file open 
6101 Bad real (read) 

6151 Attempt toreinitalize heap already in use 

6152 Bad argument to NEW (negative size) 

6153 Insufficient memory for NEW request 

6154 Attempt to RELEASE outside of heap 

Operating System Enror Codes 

The errcff codes listed below are generated only when a nonrecoverable error 
occurs while in Operating System code. 

10050 Request block is not chained to a PCB (Unblk_Req) 

10051 Bld_Req is called with interrupts off 

10100 An error was returned from SetUp Directory or a Data Segment routine 
(SetupJUInfo) 

10 102 Err or > trying to creete shell (Root) 

10103 Sem_Count > l(Init_Sem) 

10104 Could not open event channel for shell (Root) 

10197 Automatic stack expansion fault occurred in system code (Check_Stack) 

10198 Need_Mem set for current process while scheduling is disabled 
(SimpleScheduler) 

10199 Attempt to block for reason other than I/O while scheduling is disabled 
(SimpleScheduler) 

10201 Hardware exception occurred while in system code 

10202 No space left from Sigl_Excep call in Hard_Excep 

10203 Nospace left from Sigl_Excep call in Nmi_Excep 
10205 Error from Wait_Event_Chn called in Excep_Prolog 

10207 No system dataspace in Excep_Setup 

10208 No space left from SigLExcep call in range error 

10212 Error in Term_Def_Hdlfrom Enablc_Excep 

10213 Error in ForcelTerm_Excep, no space in Enq_Ex_Data 
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1040 1 Error f r om Close_Event_Chn in Ec_Cleanup 
10582 Unable to get space in Freeze_Seg 
10590 Fatal memory parity error 

10593 Unable to move memory manager segment during startup 

10594 Unable to swap in a segment during startup 

10595 UneA>le to get space in Extend_MMlist 

10596 Trying to alter size of segment that is not data or stack ( Alt_DS_Size) 

10597 Trying to allocate space to an allocated segment (Alloc_Mem) 

10598 Attempting to allocate a nonfree memory region (Take_Free) 

10599 Disk I/O error while swapping in an OS code segment. 

10600 Error attempting to make timer pipe 

1060 1 Error from Kill_Object of an ex isting timer pipe 

10602 Error from second Make_Pipe to make timer pipe 

10603 Error from Open to open timer pipe 

10604 No syslocal space for head of timer list 

10605 Error during allocate space for timer pipe, or interrupt from nonconf igured 
device 

10609 Interrupt from nonconf igured device 

106 10 Error from info about timer pipe 

106 1 1 Spurious interrupt from floppy drive #2 

10612 Spurious interrupt from floppy drive #1, or no syslocal space for timer list 
element 

10613 Error from Read_Data of timer pipe 

10614 Actual returned from Read_Data is not the same as requested from timer 
pipe 

10615 Error from open of the receiver's event channel 

106 16 Error from Vsfrite_Event to the receiver's event channel 

106 17 Error from Close_Event_Chn on the receiver's pipe 
106 19 No sysglobal space for timer request block 

10624 Attempt to shut down floppy disk controller while drive is still busy 
10637 Not enough memory to initialize system timeout drives 
10675 Spurious timeout on console driver 

10699 Spurious timeout on parallel printer driver 

10700 Mismatch between loader version number and Operating System vision 
number 

1070 1 OS exhausted its internal space during startup 

10702 Cannot make system process 

10703 Cannot kill pseudo-outer process 

10704 Cannot create driver 

10706 Cannot initialize floppy disk driver 

10707 Cannot initialize the File System volume 

10708 Hard disk mount table unreadable 

10709 Cannot map screen data 

10710 Too many slot-based devices 

10724 The boot tracks do not know the right File System version 

10725 Either damaged File System or damaged contents 

10726 Boot device read failed 
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10727 The OS will not fit into the available memory 

10728 SYSTEM.OS is missing 

10729 SYSTEM.CONFIG is corrupt 

10730 SYSTEM.OS is corrupt 

10731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

10732 SYSTEM.LLD is corrupt 

10733 Loader range error 

10734 Wrong driver is found. For instance, storing a diskette loader on a ProFile 

10735 SYSTEM.LLD is missing 

10736 SYSTEM.UNPACK is missing 

10737 Unpack of SYSTEM.OS with SYSTEM.UNPACK failed 

10738 Can't find a required driver for the boot device. 

10739 Can't load a required driver for the boot device. 

10740 Boot device won't initialize. 

1074 1 Can't boot from a serial device. 

11176 Found a pending write request for a pipe while in Close_Object when it is 
called t^ the last writer of the pipe 

11177 Found a pending read request for a pipe while in Close_Object when it is 
called by the (only possible) reader of the pipe 

11178 Found a pending read request for a pipe while in Read_Data ft om the pipe 
11180 Found a pending write request for a pipe while in Write_Datato the pipe 
118xx Error xx from diskette ROM(See OS errors 18xx) 

11^1 Call to Getspace or Relspace with a bad parameter, or free pool is bad 
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FS INFO Fields 



♦♦ defined for mounted or unmounted devices 
$ defined for mounted devices oniy 
Aii otner fields are defined for mounted biock-structured devices oniy. 



DEVICE_L VOLUME_T: 

backup_volicl 
blocksize 

* dlockstructured 
boot_code 
boot_environ 
clustersize 
copy 

copy_flag 
copy_thread 
datasize 

* devt 

^ dirj)ath 
DTCC 
DTVB 
DTVC 
DTVS 
filecount 
freecount 
fs_o\/erhead 

fs_size 
fsversion 

* iochannel 

label_size 

$ lockeddev 
machineJD 
master 
master_copy_ID 

* mounted 

$ mount jjending 
♦♦ name 
$ opencount 

overmount_stamp 

password 



ID of the volume of which this volume Is a copy. 

Number of bytes in a block on this device. 

Flag set if this device is block-structured. 

Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set if this volume is a copy. 

Count of copy operations involving this volume. 

Number of data bytes in a page on this volume. 

Device type. 

Pathname of the volume/device. 

Date/time volume was created if it is a copy. 

Date/time volume was last backed-up. 

Date/time volume was created. 

Date/time volume was last scavenged. 

Count of files on this volume. 

Count of free pages on this volume. 

Number of pages on this volume required to store 

File System data structures. 

Number of pages on this volume. 

Version number of the File System under which 

this volume was initialized. 

Number of the expansion card channel through 

which this device is accessed. 

Size in bytes of the user-defined labels associated 

with objects on this volume. 

Reserved. 

Machine on which this volume was initialized. 

Reserved. 

Reserved. 

Flag set if a volume is mounted. 

Reserved. 

Name of this volume/device. 

Count of objects open on this volume/device. 

Reserved. 

Password of this volume. 
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$ prlvatedev 


Reserved. 


privileged 


Reserved. 


$ remote 


Reserved. 


result scavenge 


Reserved. 


scavenge_flag 


Flag set Dy the Scavenger if it has altered tWs 




volume in some way. 


* slot_no 


NumDer of the expansion slot holding the card 




through which this device is accessed. 


$ unmount_pending 


Reserved. 


volid 


Unique identifier for this volume. 


vol_left_mounted 


Flag set if this volume was mounted during a 




system crash. 


volname 


Volume name. 


volnum 


Volume number. 


voljize 


Total number of blocks in the File System volume 




and boot area on this device. 


write_protected 


Reserved. 



CBJECT T: 



acmode 
dirjDath 

DTA 
DTB 
DTC 
DIM 
DTS 

eof 

etype 
file_closed_by_OS 

file_left_open 

file_scavenged 

fmark 
fs_overhead 

ftype 

fuid 

kswltch 

locked 

Ipsize 



Set of access modes associated with this refnum. 

Pathname of the directory containing this object. 

Date/time object was last accessed. 

Date/time object was last backed-up. 

Date/time object was created. 

Date/time object was last modified. 

Date/time object was last scavenged. 

Flag set if end of file has been encountered on 

this object (through the given refnum). 

Directory entry type. 

Flag set if this object was closed by the Operating 

System. 

Flag set if this object was open during a system 

crash. 

Flag set by the Scavenger if this object has been 

altered in some way. 

Absolute byte to which the file mark points. 

Number of pages used by the File System to store 

control information about this object. 

Object type. 

Unique identifier for this object. 

Flag set when the object is killed. 

Reserved. 

Number of data bytes on a page. 
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machineJD Machine on wnicn tnis oDject may be opened. 

master_file Flag set if this object is a master. 

name Entry name of this object. 

nreaders Number of processes with this object open for 

reading, 
nwriters Number of processes with this object open for 

writing, 
nusers Number of processes with this object open, 

private Flag set if this object is open for private access, 

protected Flag set if this object is protected, 

psize Physical size of this object in bytes, 

refnum Reference number for this object (argument to 

INFO). 
result_scavenge Reserved. 

safety_on value of the safety switch for this object, 

size Number of data bytes in this object (LECF). 

system_type Reserved. 

user_type User-defined type field for this object. 

user_subtype user-defined subtype field for this object. 
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accessing devices 1.3, 
ACTIVATE_PROCESS 3.8.6 
ALLOCATE 2.10.13 
Append access 2.10.8 
attritxite 1.3, 2.10.5 
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CONVERT_TIME 

creating 

a data segment 4.7.1 
an event channel 5.8. 
an object 2.10.1 
a process 3.3, 3.8.1 



baud rate 2.10.12.1 
binding 4.1 
BINO_DATASEG 4.7.12 
blocked process 1.4, 

3 (introduction), 3.8.5 
buffer 2.9, 2.10.12.1, 2.10.16, 

5.5, 5.8 



CARDS_EQUIPPED 6.1.1 

catalog 2.1, 2.5, 2.10.19 

changing file size 2.10.13-2.10.15 

clock 5.6 

clock system calls 5.9 

CLOSE_DATASEG 4.7.4 

CLOSE_E\/ENT_CHN 5.8.4 

CLOSE_OBJECT 2.10.9 

code segment 4.5 

conmunication between processes 1.7 

COMPACT 2.10.14, 2.10.15 

configuration 6 (introduction) 

configuration system calls 6.1 

controlling 

a device 2.10.12 

a process 3.4 



data segment 

creating 4.7.1 

private 4.1, 4.4 

shared 1.7, 4.1, 4.3 

swapping 4.6 
Decode mnemonics 2.10.12 
Dcdata 2.10.12 
Dctype 2.10.12 
Dcversion 2.10.12 
DECL ARE_E XCEP_HOL 5.7.1 
DELAYJIME 5.9.1 
deleting 

a process 3.8.2, 3.8.4 

an object 2.10.2 
device 2.3-2.7, 2.10.12 

accessing 1.3, 2.8 

control information 2.10,12 

mounting 1.3, 2.10.20 

names 2.1, 2.3, 2.10.12.1 

priority 2.3 

storage 2.4 
0EVICE_.CONTR0L 2.10.12 
directory 2 (introduction) 
DISABLE_EXCEP 5.7.2 
disk hard error codes 2.10.12.2 
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division by zero 5.2, B 
Dread, Dwrite access 2.10.8 



FLUSH_DATASEG 4.7.5 
FLUSH_EVENT_CHN 5.8.7 
FLUSH_EXCEP 5.7.6 
FS INFO fields E 



ENABLE_EXCEP 5.7.3 

end of file 2.7, 2.10.14, 2.10.15 

eof 2.10.5; see also end of file. 

error 

disk hard error codes 2.10.12.2 

error niessages D 

soft error 2.10.12.1 

See also exception, 
event 1.6, 5.4, C 
event channel 1.7, 5.5, 5.8.1 
event management system calls 5.8 
event types C 
exception 1.6, 5.1-5.3, B 
exception handler 5.1, 5.3 
exception management system calls 

5.7 
exception names B 



father process 1.4, 3.6, 3.7, 

3.8.1, 3.8.2 
file 2 (introduction) 

access 2.8 

attributes 2.10.5-2.10.7 

changing size 2.10.13-2.10.15 

label 2.6, 2.10.11 

marker 2.7, 2.10.15 

name 2.1, 2.10.1 

private 2.8 

shared 1.7, 2.8 
File System 1.3, 2 
File System calls 2.10 
FLUSH 2-10.16 



GET_CONFIG_NAME 6.1.2 
GET_NEXT_ENTRY 2.10.19 
GET_TIME 5.9.2 
6ET_W0RKIN6_DIR 2.10.18 
global access to files 2.8 
global event channel 5.5 
Global Refnum 2.8, 2.10.8 



handshake 2.10.12.1 
hierarchy of processes 3.2 



INFO 2.10.6 
INFO_ADDRESS 4.7.9 
INFO_DATASEG 4.7.7 
INFO_EVENT_CHN 5.8.5 
INFO_EXCEP 5.7.4 
INFO_LDSN 4.7.8 
INFO_PROCESS 3.8.3 
interface unit A 
interprocess communication 1.7, 
I/O 2 (introduction) 
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2.9 



KILL_DATASEG 4.7.2 
KILL_EVENT_CHN 5.8.2 
KILL_0BJECT 2.10.2 
KILL PROCESS 3.8.4 
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latsel, file 2.6, 2.10.11 
LDSN 4.2, 4.4, 4.7.8 
LEOF. See end of file, 
local data segment 4.1 
local event channel 5.5 
logical data segment number 4.2, 

4.4, 4.7.8 
logical end of file. See end of 

file. 
LOOKLP 2.10.5 



rt 

MAKE_DATASEG 4.7.1 

MAKE_EVENT_CHN 5.8.1 

MAKEJILE 2.10.1 

ttAKE_PIPE 2.10.1 

MAKE_PROCESS 3.8.1 

memory management 1.5, 4.1-4.6 

memory management system calls 4.7 

memory, parameter 6 (introduction) 

MEhJNFO 4.7.10 

mnemonics for Decode 2.10.12.1 

MOUNT 2.10.20 

mounting a device 1.3, 2.10.20 

MY ID 3.8.9 
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naming an object 
2.10.4 



2.1, 2.10.1, 





object 1.3 

creating 2.10.1 
deleting 2.10.2 
naming 2.1, 2.10.1 
renaming 2.10.4 



OPEN 2.10.8 
OPEN_DATASEG 4.7.3 
OPEN_EVENT_CHN 5.8.3 
OS interface A 
OSBOOTVOL 6.1.3 



page 2.4 

parameter memory 6 (introduction) 

parity 2.10.12.1 

pathname 1.3, 2.1, 2.2 

PEOF. See end of file. 

physical end of file. See end of 

file, 
pipe 1.7, 2.9. 2.10.1, 2.10.8 
priority of devices 2.3 
priority of processes 3.5, 3.8.7, 

3.8.8 
private access to files 2.8, 2.10.8 
private data segment 4.1, 4.4 
process 1.4, 5 

blocked 1.4, 3 (introduction), 
3.8.5 

creating 3.3, 3.8.1 

father 1.4, 3.6, 3.7, 3.8.1, 
3.8.2 

hierarchy 3.2 

priority 3.5, 3.8.7, 3.8.8 

queuing 3.5, 3.8.5-3.8.8 

scheduling 3.5, 3.8.5-3.8.8 

shell 1-4, 3.2 

son 1.4, 3.7, C 

starting 3.8.1, 3.8.6 

stopping 3.8.2, 3.8.4 

structure 3 . 1 

termination 1.4, 3.6, 5.2, B, C 
process system calls 3.8 
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queuing a process 3.5, 3.8.5-3.8.8 
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range check error 5.2, B 
READ_DATA 2.10.10 
READ_LABEL 2.10.11 
refnum 2.8; see also Global_Refnum. 
RENAME„ENTRY 2.10.4 
renaming an object 2.10.4 
RESETCATALOG 2.10.19 
running a program 1.4, 1.9, 3.8.1, 
3.8.6 



safety switch 2.5, 2.10.17 

Scheduler 3 

scheduling processes 3.5, 

3.8.5-3.8.8 
SEND_EVENT_CHN 5.8.8 
SETACCESS DATASEG 4.7.11 



.8.7 



.9.3 



SETPRIORITY_PROCESS 3. 
SET_FILE_INFO 2.10.7 
SET_LOCAL_TIME_DIFF 5. 
SET_SAFETY 2.10.17 
SET_WORKING_DIR 2 . 10 . 18 
shared data segment 1.7, 4.1, 4.3 
shared file 1.7, 2.8 
shell process 1.4, 3.2 
SIGNAL_EXCEP 5.7.5 
SIZE_DATASE6 4.7.6 
soft error 2.10.12.1 
son process 1.4, 3.7, C 
sparing 2.10.12 
starting a process 
stopping a process 
storage device 2.4 
SUSPEND PROCESS 3.f 



3.8.1, 
3.8.2, 



3.8. 
3.8. 



swapping 4.6 
Syscall unit A 
system calls 

clock 5.9 

configuration 6.1 

event management 5.8 

exception management 5.7 

file 2.10 

memory management 4.7 

process 3.8 
system clock 5.6, 5.9 
system-defined exceptions 5.2, B 
SYS_OVERFLOW 5.2, B 
SYS_SON_TERM C 
3YS_TERMINATE 5.2, B 
SYS_VALIJE GOB 5.2, B 
SYS ZERO_DIV 5.2, B 



terminated process 1.4, 3.6, 5.2, 

B, C 
TERriINATE_PROCESS 3.8.2 
timed events 5.8.8 
tree, process 3.2 
TRUNCATE 2.10.15 
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UNBIND_DATASE6 4.7.12 
UNKILL_FILE 2.10.3 
UNMOUNT 2.10.20 
user-defined exception handler 



5.3 



value out of bounds 5.2, B 
volume catalog 2.1, 2.5, 2.10.19 
volume name 1.3 
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working set 4.2 
WRITE_DATA 2.10.10 
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writing buffered data 2.10.16 
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Introduction 

The OEMSysCall unit provides interfaces to privileged procedures within the 
Lisa Operating System. These privileged procedures offer facilities that fall 
into two categories: disk volume management and file password protection. 

Disk Volume Management 

The OEMSysCall unit includes procediff«s to 

• Initialize a disk volume. 

■ Eject a removable disk volume. 

■ Scavenge a disk volume. 

■ Determine if two disk volumes are identical. 

File Password Protection 

A file may be protected from unauthorized access by associating a password 
with it. Password protection prevents a file from being opened, killed, or 
renamed without presentation of the proper password. Other operations (e.g.. 
Lookup, Read_Label, etc.) are unaffected by the presence of a password 
protecting the specified file. The OEMSysCall unit includes procedures to 

■ Open a password-protected file. 

■ Delete a password-protected file. 

■ Rename a password-protected file. 

• Change the password associated with a file. 

■ Verify the password associated with a file. 
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2 OEMSysCall Routines 

2.1 Init_Vol 

Init_Vol (var ecode = integer; 
devNane : e^nane; 
volNane : e^nane; 
password : e.na«e) 

ecode: Error indication (common errors are listed below) 
devName.- Name of the device to initialize 
volName: Name to assign to the new disk volume 
password: Password to assign to the new disk volume 

Initialize the volume on the specified device. The volume is assigned the 
name and password vollstame and password. Volume passwords are currently 
not supported by the Lisa file system. The volume may not be mounted on 
the device at the time of the call. 

Common errors: 

618 Cannot format the volume (make sure a diskette is in 

the drive) . 
971 Device name is invalid (check configuration). 
1167 Device is not a disk. 

1169 Could not default mount the volume in order to 
perform initialization. 

1171 Volume name contains the dash, "-", character. 

1172 No space in system heap for the volume allocation 
map of the new volume. 

1390 Volume is mounted on the device. 
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Z2 EjectVol 

EjectVol (var ecode r integer; 
devNaae : e^nane) 

ecode.- Error indication (common errors are listed below) 
devName: Name of the device from which to eject media 

Eject the removable disk media from the specified device. The device must 
support ejectable media, and the volume may not be mounted on the device 
at the time of the call. 

Common errors: 

614 No diskette present in the drive. 

971 Device name is invalid (check configuration). 

1164 Device does not support ejectable media. 

1390 Volume is mounted on the device. 
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23 Scak^engeVol 

ScavengeVol (var ecode : integer; 
devName : e_naiiie) 

ecode: Error indication (common errors are listed below] 
devName: Name of the device to scavenge 

Scavenge the volume on the specified device. The volume may not be 
mounted on the device at the time of the call. 

Common errors.- 

614 No diskette present in the drive. 

971 Device name is invalid (check configuration). 

1225 Scavenger aborted. 

1227 Device is not a disk. 

1231 Scavenger heap overflow. 

1237 Unable to repair the volume directory structure. 

1240 Volume is not in a Lisa file system format. 

1390 Volume is mounted on the device. 
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2.4 VerifyVol 

VerifyVol (var ecode = integer; 

sourceOev = e__nane; 
destinDev : e.nane; 
bufftddr : longint; 
bufSize : longint) 

ecode.- Error indication (common errors are listed below) 

sourceDev: Name of the device being verified 

destinDev: Name of the device to verify against 

bufftddr: Address of the buffer 

bufSize: Size of the buffer in bytes 

Compare the volume on sourceDev with the volume on ctestinOev. The 
volumes are compared track by track. The memory buffer used during the 
comparison is supplied by the caller and is described by its starting address 
iMjrMdr and length buTSize. The buffer must be at least large enough to 
accommodate two disk blocks of 536 bytes each (i.e., 1072 bytes). Neither 
the soLffce volume nor the destination volume may be mounted at the time 
of the call. The error indication ecoite is zero if the volumes are identical, 
and 1393 if they differ. 

Common errors: 

614 No diskette present in the drive. 

971 Source or destination device name is invalid (check 

configuration) . 
1167 Source or destination device is not a disk. 
1390 Volume is mounted on the source or destination 
device. 

1392 Supplied buffer is too small (bufSize < 1072). 

1393 Volumes are not identical. 
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23 MakeSecure 



MakeSecure (var ecode : integer; 
var path = pathnane; 
var password : e_naMe) 

ecode: Error indication (common errors are listed below) 

path: Name of the new file 

password: Password to be associated with the new file 

Create a new file protected by the specified password. This procedure 
behaves the same as Make_File. 

Common errors: 

854 Volume s-file list is full. 

855 Cannot allocate disk space for the file leader. 

890 File already exists. 

891 Volume catalog is full. 

892 File name is illegal (a file name may not contain 
the dash, "-", character). 

921 Pathname is invalid. 
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KillSecure (var ecode : integer; 
var path : pathnane; 
var password : e_nane) 

ecode: Error indication (common errors are listed below) 
path: Name of the object to be deleted 

password: Password associated with the object 



Delete the file with the specified name and password. The deletion is 
allowed if password does not match the password assigned to the file, 
procedure behaves the same as Kill_Object. 

Common errors: 



not 
This 



-1293 Warning: the file was not password protected. The 
kill operation completes normally. 

894 File cannot be found. 

895 File name is illegal. 

896 File safety switch is set (the file is protected 
against deletion) . 

1294 Supplied password does not match the password 

protecting this file. 
1298 File cannot be accessed because its s-list entry is 

damaged. 
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2.7 OpenSecure 

OpenSecure (var ecode : integer; 
var path = pathnane; 
var refnim : integer; 

nanip : mset; 
var password = e.nane) 

ecode: Error indication (common errors are listed below) 

path: Name of object to be opened 

refnum: Reference number for the object 

manip: Set of access types 

password: Password associated with the object 

Open the file with the specified name and password. The open is not done if 
password does not match the password assigned to the file. This procedure 
behaves the same as Open. 

Common errors: 

-1173 Warning: this file was last closed by the Operating 

System. 
-1174 Warning: this file was open during a system crash. 
-1175 Warning: this file has been reconstructed by the 

scavenger. 
-1176 Warning: the contents oT this file has been 

reconstructed by the scavenger. 
-1293 Warning: the file was not password protected. The 

open operation completes normally. 

871 File cannot be accessed because its s-list entry is 
damaged. 

872 No space in system heap for File Control Block. 

873 File is open for priK-'ate access by another process. 

946 Pathname is invalid. 

947 No space in the system heap for File Refnum 
Descriptor Block. 

948 File cannot be found. 

949 Request for prii-'ate access is disallowed because the 
file is open for access by another process. 

1130 Open request violates software theft protection 

policy. 
1294 Supplied password does not match the password 

protecting this file. 
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2.8 RenameS«:ure 

RenaneSecure (var ecode : integer; 
var path : pathnane; 
var neMNane : e.name; 
var password : e_nane) 

ecode: Error indication (common errors are listed below) 

path: Name of the object to be renamed 

newName: New name for the object 

password: Password associated with the object 

Rename the file with the specified name and password. The rename is not 
done if password does not match the password assigned to the file. This 
procedure behaves the same as Rename_Entry. 

Common errors: 

-1293 Warning: the file was not password protected. The 
rename operation completes normally. 

1021 Pathname is invalid. 

1022 File cannot be found. 

1023 New file name is illegal (a file name cannot contain 
the dash, "-", character). 

1024 File having the new name already exists. 
1294 Supplied password does not match the password 

protecting this file. 

1296 File name string variable has bad length byte. 

1297 File cannot be accessed because its leader is 
damaged. 

1298 File cannot be accessed because its s-list entry is 
damaged. 
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2.9 VerifyPassword 

VerifyPassword (var ecode : integer; 
var path : pathname; 
var password : e_naiie) 

ecode: Error indication (common errors are listed below) 
path: Name of the file whose password is to be verified 

password: Password to be verified 

Compere the specified password with the password protecting the specified 
file. The error indication axude is zero if the passwords are identical, and 
1294 if they differ. 

Common errors: 

-1293 Warning: the file was not password protected. The 
verify operation completes normally. 

1091 Pathname is invalid. 

1092 File cannot be found. 

1297 File cannot be accessed because its leader is 
damaged. 

1298 File cannot be accessed because its s-list entry is 
damaged. 

1294 Supplied password does not match the password 
protecting this file. 



1-10 



Lisa S^<stems SonwsFe OEMS^'SCal! 



ZIO ChangfsPassword 

ChangePassMord (var ecode : integer; 
var path : pathname; 
var olcPassiford : e_nane; 
var neifPassiford : e_naiie) 

ecode: Error indication (common errors are listed 

below) 
path: Name of the file whose password is to be 

changed 
oldPassword: Current password associated with the file 
newPassword: New password to be associated with the file 

Change the password associated with the specified file. The change is not 
done if oldPassword does not match the password assigned to the file. This 
call may be used to assign a password to a file for the first time. 

Common errors: 

-1293 Warning: the file was not password protected. The 
change operation completes normally. 

1091 Pathname is invalid. 

1092 File cannot be found. 

1297 File cannot be accessed because its leader is 
damaged. 

1298 File cannot be accessed because its s-list entry is 
damaged. 

1294 Supplied old password does not match the password 
protecting this file. 
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3 Interface 

UNIT OEMsysceai; 

INTERFACE 

USES 

(*$U Syscall.obj *) syscall, 
(*$U Psyscall.obj *) psyscall; 

procedure EXCTV0L(v8ir errnura:integer;clevnairoe:e_n8rae); 

procedure a;ftVENG£VOL(var errnum : integer; devnarae:e_neme); 

proceditre INITJ/OL(var errnum:integer;devnaroe:e_neme;voln8rae:e_n8me; 
password : e_name); 

procedure VERI FYVOL ( var errnum : i nt eger; sour cedev : e_nane; dest dev -. e_nane; 
buffaddr:longint;buffsize:longint); 

procedure Ml¥<ESEa*E(v8ir err nun: integer; var path: pathname; var 
passwd:e_n8me); 

procedure KILLSECLff?E(var errnim: integer; var path: pathname; var 
passwd:e_name); 

procedure OPENSECXI?E(var errnum: integer; var path: pathname; var refnum: integer; 
raanip:mset;var passwd:e_name); 

procedure FEN(VCSECLRE(var errnLm: integer; var path: pathname; var 

newname : e_name; var passwd:e_n8me); 

procedure ^RIFYPASa«0?D(var errnum: integer; var path: pathname; var 

passwd:e_name); 

procedure CHfH3£PASSW0RD(var errnum: integer; var path: pathname; var 

oldpasswd:e_name; var newpasswd:e_name); 
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Introduction 

This manual describes the Standard Apple Numeric Environment (SANE). 
Apple supports SANE on several current products and plans to support SANE 
on future products. SANE gives you access to numeric facilities unavailable 
on almost any computer of the early 1980s~from microcomputers to 
extremely fast^ extremely expensive supercomputers. The core features of 
SANE are not exclusive to Apple; rather they are taken from Draft 10.0 of 
Standard 754 for Binary Floating-Point Arithmetic [10] as proposed to the 
Institute of Electrical and Electronics Engineers (IEEE). Thus SANE is one of 
the first widely available products with the arithmetic capabilities destined 
to be found on the computers of the mid-1980s and beyond. 

The IEEE Standard specifies standardized data types^ arithmetic^ and 
conversions^ along with tools for handling limitations and exceptions, that are 
sufficient for numeric applications. SANE supports all requirements of the 
IEEE Standard. SANE goes beyond the specifications of the Standard by 
including a data type designed for accounting applications and by including 
several high-quality library functions for financial and scientific calculations. 

IEEE arithmetic was specifically designed to provide advanced features for 
numerical analysts without imposing extra burden on casual users. (This is 
an admirable but rarely attainable goal: text editors and word processors, for 
example, typically suffer increased complexity with added features, meaning 
more hurdles for the novice to clear before completing even the simplest 
tasks.) The independence of elementary and advanced features of the IEEE 
arithmetic was carried over to SANE. 
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2 Date Types 

SANE provides three explication data types (single, double, and comp) and 
the arithmetic type (extended). Single, double, and extended store 
floating-point values and connp stores integral values. 

The extended type is called the arithmetic type because, to make expression 
evaluation simpler and more accurate, SANE performs all arithmetic 
operations in extended precision and delivers arithmetic results to the 
extended type. Single, dmjble, and cmnp can be thought of as space-saving 
storage types for the extended-precision arithmetic. (In this manual, we 
shall use the term extended precision to denote both the extended precision 
and the extended range of the extended type.) 

All values representable in single, double, and comp (as well as 16-bit and 
32-bit integers) can be represented exactly in extended. Thus values can be 
moved from any of these types to the extended type and back without any 
loss of information. 

2.1 Choosing a Data Type 

Typically, picking a data type requires that you determine the trade-offs 
between 

- Fixed- or floating-point form, 

■ Precision, 

■ Range, 

- Memory usage, said 

- Speed. 

The precision^ range, and memory usage for each SANE data type are shown 
in Table 2-1. Effects of the data types on performance (speed) vary among 
the implementations of SANE. (See Section 4 for information on conversion 
problenns relating to precision.) 

Most accounting applications require a counting type that counts things 
(pennies, dollars, widgets) exactly. Accounting applications can be 
implemented by representing money values as integral numbers of cents or 
mils, which can be stored exactly in the storage format of the comp (for 
computational) type. The sum, diffa-ence, or product of any two comp values 
is exact if the magnitude of the result does not exceed 2^2-1 (that is, 
9,223,372,036,854,775,807). This number is larger than the U.S. national debt 
expressed in Argentine pesos. In addition, comp values (such as the results 
of accounting computations) can be mixed with extended values in 
floating-point computations (such as compound interest). 

Arithmetic with comp-type variables, like all SANE arithmetic, is done 
internally using extended-precision sarithmetic. There is no loss of precision, 
as conversion from comp to extended is always exact. Space can be saved 
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by storing numbers in the comp type, which is 20 percent shorter than 
extended. Nonaccounting applications will normally be better served by the 
floating-point data formats. 

2L2 Values Represented 

The floating-point storage formats (single, double, and extended) provide 
binary encodings of a sign (+ or -), an exponent^ and a signiticand A 
represented number has the value 

♦significand * 2«'<P"«"* 

where the significand has a single bit to the left of the binary point (that is, 
< significand < 2). 

23 Range and Precision of SfiNE Types 

This table describes the range and precision of the numeric data types 
supported by SANE. Decimal ranges are expressed as chopped two-digit 
decimal representations of the exact binary values. 
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Table 2-1 
SANE Types 



Type class 


ftppli cation 




Arithmetic 


Type identifier Single 


Double 


Comp 


Extended 


Size (bytes:bits) 4:32 


8:64 


8:64 


10:80 


Binary exponent 
range 
Minimum -126 


-1022 




-16383 



Significand 
precision 

Bits 

Decimal digits 



24 
7-8 



53 
15-16 



63 
18-19 



64 
19-20 



Decimal range 

(approximate) 

Min negative -3.4E+38 -1.7E+308 

Max neg norm -1.2E-38 -2.3E-308 

Max neg denorm* -1.5E-45 -5.0E-324 

Min pos denorm* 1.3E-45 5.0E-324 

Min pos norm 1.2E-38 2.3E-308 



-9.2E18 



-l.lE+4932 
■1.7E-4932 
■1.9E-4951 

1.9E-4951 
1.7E-4932 



Max positive 3.4E+38 


i.7E+308 


« 9.2E18 


l.lE+4932 


Infinities* Yes 


Yes 


No 


Yes 


NaNs* Yes 


Yes 


Yes 


Yes 


* Dencarmsidenormalized numter^^ 
defined in Section 7. 


Nah^ (Not-a 


-Numderi, and 


infinities are 



Usually numbers are stored in a normalized form, to afford maximum 
precision for a given significand width. Maximum precision is achieved if 
the high order bit in the significand is 1 (that is, 1 i significand < 2). 
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Example 

In Single, the largest representable number has 

significand = 2 - 2-^ 

I.IIIIIIIIIIIIIIIIIIIIIII2 

exponent = 127 

value = (2 - 2-23) * 212? 

» 3.403 * 1038 

the smallest representable positive normalized number has 

significand = 1 

1 .OOOOOOOOOOOOOOOOOOOOOOO2 

exponent = -126 

value = 1 * 2-i2« 

~ 1.175 * 10-38 

and the smallest representable positive denormalized number (see Section 7) 
has 

significand = 2-23 

O.OOOOOOOOOOOOOOOOOOOOOOI2 

exponent = -126 

value = 2-23 * 2-126 

« 1.401 * 10-«5 

2.4 Forinats 

This section shows the formats of the four SANE numeric data types. These 
are pictorial representations and may not reflect the actual byte order in any 
particular implementation. 

Single 

A 32-bit single format number is divided into three fields as shown below. 

1 8 23 widths 

kl e I f __ "__ i 

nisb Isb msb Isb order 
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The value v of the number is determined by these fields as follows: 

if < e < 255, then v » (-l)s * 2<e-i27) * (i.f). 

if e = and f * 0, then v = (-1)* ♦ 2<-^^> * (O.f); 

if e = and f » 0, then v = (-1)^ * O; 

if e = 255 and f = 0, then v = (-1)^ * «; 

if e « 255 and f * 0, then v Is a NaN. 

See Section 7 for information on the contents of the f field for NsNs. 

Double 

A 64-bit double format number is divided into three fields as shown below. 

1 11 52 widths 

IsJ __ e |_ ~ ~r "I'll 

rosb Isb msb Isb order 

The value v of the number is determined by these fields as follows: 

if < e < 2047, then v = (-l)s * 2<e-«>23> * (I.f); 

if e = and f * 0, then v = (-l)s * 2<-i022) * (O.f); 

if e = and f = 0, then v = (-1)* * 0; 

if e = 2047 and f = 0, then v = (-l)s * •; 

if e = 2047 and f * 0, then v is a NaN. 

Comp 

A 64-bit comp format number is divided into two fields as shown below. 

1 63 widths 

___ ~""~~d ™~ 

rosb Isb order 
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The value v of the number is determined by these fields as follows: 

if s « 1 and d = 0, then v is the unique comp NaN; 

otherwise, v is the two's-complement value of the 64-bit representation. 

Ext^ided 

An 80-bit extended format number is divided into four fields as shown below. 

1 15 1 63 widths 

|s| e In " ~ f I 

rosb Isb msb Isb order 

The value v of the number is determined by these fields as follows: 
if <= e < 32767, then v = (-l)s * 2<e-i6383) * (i.f). 

if e » 32767 and f = 0, then v = (-1)^ * «, regardless of i; 
if e » 32767 and f * 0, then v is a NaN, regardless of i . 
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3 firitivmiic Operations 

SANE provides the basic arithmetic operations for the SANE data types: 

- Add. 

■ Subtract. 

■ Multiply. 

■ Divide. 

• Square root. 

■ Remainder. 

" Round to integral value. 

All the basic arithmetic operations produce the best possible result: The 
mathematically exact result coerced to the precision and range of the 
extended type. The coercions honor the user-selectable rounding direction 
and handle all exceptions according to the requirements of the IEEE Standard 
(see Section 8). See Sections 9 and 10 for auxiliary operations and 
higher-level functions supported by SANE. 

3.1 Remairater 

Generally, remainder (and mod) functions are defined by the expression 

X rem y = x - y * n 

where n is some integral approximation to the quotient x/y. This expression 
can be found even in the conventional integer-division algorithm: 

n (integral quotient approximation) 

(divisor) y) x (dividend) 

y * n 

X - y ♦ n (remainder) 

SANE supports the remainder function specified in the IEEE Standard: 

When y * 0, the remainder r = x rem y is defined regardless of the rounding 
direction by the mathematical relation r = x - y * n, where n is the integral 
value nearest the exact value x/y; whenever |n - x/y| = 1/2, n is even. The 
remainder is always exact. If r = 0, its sign is that of x. 
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Example 1 

Find 5 rem 3 . Here x = 5 and y = 3. Since 1 < 5/3 < 2 and since 5/3 = 
1.66666... is closer to 2 than to 1^ n is taken to be 2, so 

5 rem 3 = r = 5-3*2 = -1 

Example 2 

Find 7.0 rem 0.4 . Since 17 < 7.0/0.4 < 18 and since 7.0/0.4 » 17.5 is equally 
close to both 17 and 18, n is taken to be the even quotient, 18. Hence, 

7.0 rem 0.4 = r = 7.0 - 0.4 * 18 = -0.2 

The IEEE remainder function differs from other commonly used remainder 
and mod functions. It returns a remainder of the smallest possible 
magnitude, and it always returns an exact remainder. All the other 
remainder functions can be constructed from the IEEE remainder. 

33. Round to Integral Value 

An input argument is rounded according to the current rounding direction to 
an integral value and delivered to the extended format. For example, 
12345678.875 rounds to 12345678.0 or 12345679.0. (The rounding direction, 
which can be set by the user, is explained fully in Section 8.) 

Note that, in each floating-point format, all values of sufficiently great 
magnitude are integral. For example, in single, numbers whose magnitudes 
are at least 223 are integral. 
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Conveisions 

SANE provides conversions between the extended type and each of the other 
SANE types (single, double, and comp). A particular SANE implementation 
v/ill provide conversions between extended and those numeric types supported 
in its particular larger environment. For example, a Pascal implementation 
will have conversions between extended and the Pascal integer type. 



I single I jsystaih-specificj 

I double I i extended] | integral | 

Icorop I I types | 



SANE implementations also provide either conversions between decimal 
strings and SANE types, or conversions between a decimal record type and 
SANE types, or both. Conversions between decimal records and decimal 
strings may be included too. 



j decimal str i ng j 

{single | 

I double i I 

icomp I I 

(extended! 



I decimal record 



4.1 COTMarsiims between Extended and Single or i3cHA>le 

A conversion to extended is always exact. A conversion from extended to 
single or double moves a value to a storage type with less range and 
precision, and sets the overflow, underflow, and inexact exception flags as 
appropriate. (See Section 8 for a discussion of exception flags.) 

4.2 ConMersitms to Con^ tmd Other Integral Formats 

Conversions to integral formats are done by first rounding to an integral 
value (honoring the current rounding direction) and then, if possible, 
delivering this value to the destination format. If the source operand of a 
conversion from extended to comp is a NaN, an infinity, or out-of -range for 
the comp format, then the result is the comp NaN and for infinities and 
values out-of -range, the invalid exception is signaled. If the source operand 
of a conversion to a system-specific integer type is a NaN, infinity, or 
out-of -range for that format, then invalid is signaled (unless the type has an 
appropriate representation for the exceptional result). NaNs, infinities, and 
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out-of -range values are stored in a two's-complement integer format as the 
extreme negative value (for example, in the 16-bit integer format, as 
-32768). 

Note that IEEE rounding into integral formats differs from most common 
rounding functions on halfway cases. With the default rounding direction (to 
nearest), conversions to comp or to a system-specific integer type will round 
0.5 to 0, 1.5 to 2, 2.5 to 2, and 3.5 to 4, rounding to even on halfway cases. 
(Rounding is discussed in detail in Section 8.) 

43 Corversions between Binary and Decimal 

The IEEE Standard for binary floating-point arithmetic specifies the set of 
numerical values representable within each floating-point format. It is 
important to recognize that binary storage formats can exactly represent the 
fractional part of decimal numbers in only a few cases; in all other cases, 
the representation will be approximate. For example, 0.5io, or l/2io, can be 
represented exactly as 0.I2. On the other hand, O.lio, or l/lOio, is a 
repeating fraction in binary: 0.000110011CX)....2. Its closest representation in 
single is 0.000 1 100 IICX) 1100 1100 11001 10 12, which is closer to 0. 10000000 149io 
than to O.lOOOOOOOOOOio- 

As binary storage formats generally provide only close approximations to 
decimal values, it is important that conversions between the two types be as 
accurate as possible. Given a rounding direction, for every decimal value 
there is a best (correctly rounded) binary value for each binary format. 
Conversely, for any rounding direction, each binary value has a corresponding 
best decimal representation for a given decimal ftMrmat. Ideally, 
binary-decimal conversions should obtain this best value to reduce 
accumulated errors. Convo'sion routines in SANE implementations meet or 
exceed the stringent error bounds specified by the IEEE Standard. This 
means that although in extreme cases the conversions do not deliver the 
correctly rounded result, the result delivered is very nearly as good as the 
correctly rounded result. (See the IEEE Standard [10] for a more detailed 
description of error bounds.) 

43.1 Convcasions from Decimal Strings to SfiNE Types 

Routines may be provided to convert numeric decimal strings to the SANE 
data types. These routines are provided for the convenience of those who do 
not wish to write their own parsers and scanners. Examples of acceptable 
input are 

123 123.4E-12 -123. .456 3e9 -0 

-INF Inf NflN(12) -NaN() nan 

The 12 in NAN(12) is a NaN code (see Section 8). 

The accepted syntax is formally defined, using Backus-Maur form, in Table 
3-1: 
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Table 4-1. 
Syntax fcr String Conversions 



<decimal number > 

<left decimal) 

<unslgned decimal) 

<finite number) 

<significand) 

<integer) 

<digits) 

<mixed) 

<exponent> 

<infinity) 

<NftN> 



[{space I tab}] <left decimal) 

[+|-] <unsigned decimal) 

<finite number) j <infinity) i <NflN) 

<significand) I<exponent)3 

<integer) | <mixed) 

<digits) [.] 

{0 ! 1 I 2 I 3 I 4 j 5 I 6 I 7 I 8 I 9} 

[<digits)] . <digits) 

E [+1-3 <digits) 

INF 

NftN[([<digits)])] 



Note: Square brackets enclose optional itenns^ curly brackets enclose 
elements to be repeated at least once^ and vertical bars separate 
alternative elements; letters that appear literally, like the £ marking the 
exponent field, may be either upper or lower case. 



43JZ Def^orm Records and Conversions from SfiNE types to Decimal Stringis 

Each conversion to a decimal string is controlled by a decfcnrm record, which 
contains two fields: 

style — 16-bit integer (0 or 1) 
digits ~ 16-bit integer 

Style equals for floating and 1 for fixed. Digits gives the number of 
significant digits for the floating style and the number of digits to the right 
of the decimal point for the fixed style (digits may be negative if the style 
is fixed). Decimal strings resulting from these conversions are alweiys 
acceptable input for conversions from decimal strings to SANE types. 
Further formatting details are implementation dependent. 
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433 The Decimal Record Type 

The decimal record type provides an intermediate unpacked form for 
programmers who wish to do their own parsing of numeric input or 
formatting of numeric output. The decimal record format has three fields: 

sgn — 16-bit integer (0 or 1) 

exp — 16-bit integer 

sig — string (maximum length is impl anient at ion- dependent) 

The value represented is 

(-l)sgn * sig * lOexp 

when the length of sig is 18 or less. (Some implementations allow additional 
information in characters past the eighteenth.) Sig contains the integral 
decimal signlficand: the initial byte of sig (si^OD is the length byte, which 
gives the length of the ASCII string that is left-justified in the remaining 
bytes. Sgn is for ♦ and 1 for -. For example, if sgn = 1, exp = -3, and 
sig » '85' (sig[0] = 2, not shown), then the number represented is -0.085. 

43.4 Conversions from Decimal Records to SMJE Types 

Conversions from the decimal record type handle any sig digit-string of 
length 18 or less (with an implicit decimal point at the right end). The 
following special cases apply: 

■ If sig[l] = '0' (zero), the decimal record is converted to zero. For 
example, a decimal record with sig = '0913' is converted to zero. 

■ If sig[l] = 'N', the decimal record is converted to a NaN. Except when 
the destination is of type comp (which has a unique NaN), the 
succeeding characters of sig are interpreted as a hex representation of 
the result significand: if fewer than 4 characters follow N then they are 
right justified in the high-order 15 bits of the field f illustrated under 
Formats in Section 2; if 4 or more characters follow N then they are 
left justified in the result's significand; if no characters, or only O's, 
follow N, then the result NaN code is set to nanzero » 15 (hex). 

■ If sig[i] « T and the destination is not of comp type, the decimal 
record is converted to an infinity. If the destination is of comp type, 
the decimal record is converted to a NaN and invalid is signaled. 

> Other special cases produce undefined results. 
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43.3 CcNTiversions from SANE Types to Decimal Records 

Each conversion to a decimal record is controlled by a decform record (see 
above). All implementations allow at least 18 digits to be returned in sig. 
The implied decimal point is at the right end of sig, with exp set 
accordingly. 

Zeroes, infinities, and NaNs are converted to decimal records with sig parts 
(zero), I, and strings beginning with N, while exp is undefined. For NaNs, 
N may be followed by a hex representation of the input significand. The 
third and forth hex digits following N give the NaN code. For example, 
•N0021000000000000' has NaN code 21 (hex). 

When the number of digits specified in a decform record exceeds an 
implementation maximum (which is at least 18), the result is undefined. 

A number may be too large to represent in a chosen fixed style. For 
instance, if the implementation's maximum length for sig is 18, then 10^^ 
(which requires 16 digits to the left of the point in fixed-style 
representations) is too large for a fixed-style representation specifying more 
than 2 digits to the right of the point. If a number is too large for a chosen 
fixed style, then (depending on the SANE implementation) one of two results 
is returned: an implementation may return the most significant digits of the 
number in sig and set exp so that the decimal record contains a valid 
floating-style representation of the number; alternatively, an implementation 
ma/ simply set the string sig to '?'. In any implementation, the test 

C-exp <> decromi digits) or (sig[l} = '?') 

determines whether a nonzero finite number is too large for the chosen fixed 
style. 

4.4 ConversicMns bet^A^sn Di^imal Formaits 

SANE implementations may provide conversions between decimal strings and 
decimal records. 

4.4.1 Conversion from Dt^^imal Strings to Decimal Records 

This conversion routine is intended as an aid to programmers doing their own 
scanning. The routine is designed for use either with fixed strings or with 
strings being received (interactively) character by character. An integer 
argument on input gives the starting index into the string and on output is 
one greater than the index of the last character in the numeric substring just 
parsed. The longest pc^sible numeric substring is parsed; if no numeric 
substring is recognized, then the index remains unchanged. Also, a Boolean 
argument is returned indicating that the input string, beginning at the input 
index, is a valid numeric string or a valid prefix of a numeric string. The 
accepted input for this conversion is the same as for conversions from 
decimal strings to SANE types (see above). Output is the same as for 
conversions from SANE types to decimal records (also above). 
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Examples 



Input String 


Index 
in out 


Output Value 


Valid Prefix 


12 


1 3 


12 


TRIF 


12E 


1 3 


12 


TRUE 


12E- 


1 3 


12 


TRIF 


12E-3 


1 6 


12E-3 


TRUE 


12E-X 


1 3 


12 


FALSE 


12E-3X 


1 6 


12E-3 


FALSE 


X12E-3 


2 7 


12E-3 


TRUE 


IN 


1 1 


UNDEFINED 


TRUE 


INF 


1 4 


INF 


TRUE 



4.4J2 Ccwcvsion from Decimal Records to Decimal Strings 

This conversion is controlled by the style field of a decform record (the 
digits field is ignored). Input is the sanne as for conversions from decimal 
records to SANE types^ and output formatting is the same as for conversions 
from SANE types to decimal strings. This conversion, actually a formatting 
operation, is exact and signals no exception. 
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3 Exiression Boduefcion 

SANE arithmetic is extended-based. Arithmetic operations produce results 
with extended precision and extended range. For minimal loss of accuracy in 
more complicated computations, you should use extended temporary variables 
to store intn^mediate results. 

:}.l Ubing ExteniSed Temporaries 

A programmer may use extended temporaries deliberately to reduce the 
effects of round-off error^ overflow, and underflow on the final result. 

Example I 

To compute the single-precision sum 

S = X113*Y[13 + X[23*Y[23 + ... + X[N]*Y{N] 

where X and Y are arrays of type single, declare an extended variable XS 
and compute 

XS :»0; 

FORI :» 1 TD N DO 

XS :« X5 •*- X[I]*Y[I]; I extended-precision arithwtic } 

S :B XS; {deliver final result to single.} 

Even when input and output values have only single precision, it may be very 
difficult to prove that single-precision arithmetic is sufficient for a given 
calculation. Using extended-precision arithmetic for intermediate values will 
often improve the accuracy of single-precision results more than virtuoso 
algorithms would. Likewise^ using the extra range of the extended type for 
intermediate results may yield correct final results in the single type in 
cases when using the single type for intermediate results would cause an 
overflow or a catastrophic underflow. Extended-precision arithmetic is also 
useful for calculations involving double or comp variables: see Example 2. 

3.2 Extended-Rrecision Expression Evaluation 

High-level languages that support SANE evaluate all non-integ^ numeric 
expressions to extended precision, regardless of the types of the operands. 
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Example 2 

If C is of type comp and MAXCOMP is the largest comp value, then the 
right-hand side of 

C := (MftXCOMP + HftXCOMP) / 2 

would be evaluated in extended to the exact result C = MAXCOMP, even 
though the intermediate result MAXCOMP + MAXCOMP exceeds the largest 
possible comp value. 

53 Extencted-Rrecision Expression Evaluation and the IEEE Standard 

The IEEE Standard encourages extended-precision expression evaluation. 
Extended evaluation will on rare occasions produce results slightly different 
fYom those produced by other IEEE implementations that lack extended 
evaluation. Thus in a single-only IEEE implementation, 

z := X + y 

with X, y, and z all single, is evaluated in one single-precision operation, 
with at most one rounding error. Under extended evaluation, however, the 
addition x ••• y is performed in extended, then the result is coerced to the 
single precision of z, with at most two rounding errors. Both 
implementations conform to the standard. 

The effect of a single- or double-only IEEE implementation can be obtained 
under SANE with rounding precision control, as described in Section 8. 
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Coinp&nson& 

SANE supports the usual numeric comparisons: less, less-or-equal, greater, 
greater-or-equal, equal, and not-equal. For real numbers, these comparisons 
behave according to the familiar ordering of real numbers. 

SANE comparisons handle NaNs and infinities as well as real numbers. The 
usual trichotomy for real numbers is extended so that, for any SANE values a 
and b, exactly one of the following is true: 

a < b 
a > b 
a = b 
a and b are unordered 

Determination is made by the rule: 

If X or y is a NaN, then x and y are unordered; otherwise, x and y are less, 
equal, or greater according to the ordering of the real numbers, with the 
understanding that +0 = -0 = real 0, and -» < each real number < ♦». 

(Note that a NaN always compares unordered — even with itself.) 

The meaning of high-level language relational operators is a natural 
extension of their old meaning based on trichotomy. For example, the Pascal 
or BASIC expression x <= y is true if x is less than y or if x equal y, and is 
false if X is greater than y or if x and y are unordered. Note that the SANE 
not-equal relation means less, greater, or unordered— even if not-equal is 
written <>, as in Pascal and BASIC. High-level languages supporting SANE 
supplement the usual comparison operators with a function that takes two 
numeric arguments and returns the appropriate relation (less, equal, greater, 
or unordered). This function can be used to determine whether two numeric 
representations satisfy any combination of less, equal, greater, and unordered. 

A high-level language comparison that involves a relational operator 
containing less or greater, but not unordered, signals invalid if the operands 
are unordered (that is, if either operand is a NaN). For example, in Pascal or 
BASIC if X or y is a quiet NaN then x < y, x <= y, x >= y, and x > y signal 
invalid, but x = y and x <> y (recall that <> contains unordered) do not. If a 
comparison operand is a signaling NaN, then invalid is always signaled, just 
as in arithmetic operations. 
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7 inrinities^ NaNs^ and Demrmelized Numbers 

In addition to the normalized numbers supported i3y most floating-point 
packages^ IEEE floating-point arithmetic also supports infinities, NaNs, and 
denormalized numbers. 

7.1 InTinities 

An infinity is a special bit pattern that can arise in one of two ways: 

■ When a SANE operation should produce an exact mathematical infinity 
(such as 1/OX the result is an infinity bit pattern. 

■ When a SANE operation attempts to produce a number with magnitude 
too great for the number's intended floating-point storage format, the 
result may (depending on the current rounding direction) be an infinity 
bit pattern. 

These bit patterns (as well as NaNs, introduced next) are recognized in 
subsequent operations and produce predictable results. The infinities, one 
positive (tlNF) and one negative (-INF) , generally behave as suggested by 
the theory of limits. For example, 1 added to +INF yields +INF; -1 divided 
by +0 yields -INF; and 1 divided by -INF yields -0. 

Each of the storage types single, double, and extended provides unique 
representations for +INF and -INF. The comp type has no representations for 
infinities. (An infinity moved to the comp type becomes the comp NaN.) 

7J2 KMsIs 

When a SANE operation cannot produce a meaningful result, the operation 
delivers a special bit pattern called a A/aV (Not-a-Number). For example, 
divided by 0, +INF added to -INF, and sqrt(-l) yield NaNs. A NaN can occur 
in any of the SANE storage types (single, double, extended, and comp); but, 
generally, system-specific integer types have no representation for NaNs. 
NaNs propagate through arithmetic operations. Thus, the result of 3.0 added 
to a NaN is the same NaN (that is, has the same NaN code). If two 
operands of an operation are NaNs, the result is one of the NaNs. NaNs are 
of two kinds: quiet Ms^ the usual kind fnroduced by floating-point 
operations; and signaling A/aAi& When a signaling NaN is encountered as an 
operand of an arithmetic operation, the invalid-operation exception is 
signaled and, if no halt occurs, a quiet NaN is the delivered result. Signaling 
NaNs could be used for uninitialized variables. They are not created by any 
SANE operations. The most significant bit of the field f illustrated under 
Formats in Section 2 is clear fen* quiet NaNs and set for signaling NaNs. 
The unique comp NaN generally behaves like a quiet NaN. 

A NaN in a floating-point format has an associated NaN code that indicates 
the NaN's origin. (These are listed in Table 7-1). The NaN code is the 8th 
through 15th most significant bits of the field f illustrated in Section 2. The 
comp NaN is unique and has no NaN code. 
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Table 7-1. 
SANE NaN Codes 



Name 



Dec Hex Meaning 



NANSORT 


1 


$01 


NANflDD 


2 


$02 


NANDIV 


4 


$04 


NANMUL 


6 


$08 


NftNREM 


9 


$09 


NANASCBIN 


17 


$11 


NftTCOMP 


20 


$14 


NftfCERO 


21 


$15 


NftNTRIG 


33 


$21 


NANINVTRIG 


34 


$22 


NANLOG 


36 


$24 


MANPOWER 


37 


$25 


NANFINAN 


38 


$26 


NANINIT 


255 


$FF 



Invalid square root^ such as scp:t(-l) 
Invalid addition, such as (+INF) - (+INF) 
Invalid division, such as 0/0 
Invalid multiplication, such as * INF 
Invalid remainder or mod such as x ran 
Attempt to convert invalid ASCII string 
Result of converting corop NaN to floating 
Attempt to create a NaN with a zero code 
Invalid argument to trig routine 
Invalid argument to inverse trig routine 
Invalid argument to log routine 
Invalid argument to xi or xy routine 
Invalid argument to financial function 
Uninitialized storage (signaling NsN) 



73 Denarmalized Numbers 

Whenever possible, floating-point numbers are normalized to keep the 
leeiding significand bit 1: this maximizes the resolution of the storage type. 
When a number is too small for a normalized representation, leading zeros 
are placed in the significand to produce a denormalized representation. f\ 
denormalized number is a nonzero number that is not normalized and whose 
exponent is the minimum exponent for the stcKrage type. 

ExmrpJe 

The sequence below shows how a single-precision value becomes 
([n-ogressively denormalized as it is repeatedly divided by 2, with rounding to 
nearest. This process is called gradual imd&flow. 

Ao =1.100 1100 1100 1100 1100 1101 * 2-"6 » o.lio * 2-^22 

Ai » Ab/2 = 0.110 0110 0110 0110 0110 0110 ♦ 2-^26 (underflow) 

Az = Ai/2 « 0.011 0011 0011 0011 0011 0011 * Tr"^ 

% - A2/2 = 0.001 1001 1001 1001 1001 1010 * 2-i26 (underflow) 
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ft22 = A2i/2 = 0.000 0000 0000 0000 0000 0011 * 2-126 

ft23 = A22/2 = 0.000 0000 0000 0000 0000 0010 * 2-126 (underflow) 

A2a = A23/2 = 0.000 0000 0000 0000 0000 0001 ♦ ^l26 

A25 = A2a/2 = 0.0 (underflow) 

Ai...A24 are denormalized; 1^4 is the smallest positive denormalized number 
in single type. 

73.1 Why Denonnalized Numbers? 

The use of denormalized numbers makes statements like the following true 
for all real numbers: 

X - y « if and only if x = y 

This statement is not true for most older systems of computer arithmetic, 
because they exclude denormalized numbers. For these systems, the smallest 
nonzero number is a normalized number with the minimum exponent; when 
the result of an operation is smaller than this smallest normalized number, 
the system delivers zero as the result. For such flush-tch-z&ro systems, if x 
* y but X - y is smaller than the smallest normalized number, then x - y « 
0. IEEE systems do not have this defect, as x - y, although denormalized, is 
not zero. 

(A few old programs that rely on premature flushing to zero may require 
modification to work properly under IEEE arithmetic. For example, some 
progranns may test x - y « to determine whether x is very near y.) 

7.4 Inquiries: Qass and Sign 

Each valid representation in a SANE data type (single, double, comp, or 
extended) belongs to exactly one of these classes: 

■ Signaling NaN. 
- Quiet NaN. 

■ Infinite. 
• Zero. 

" Normalized. 
> Denormalized. 

SANE implementations provide the user with the facility to determine easily 
the class and sign of any valid representation. 

Environmental controls include the rounding direction, rounding precision, 
exception flags, and halt settings. 
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8 Bnvironmental Control 

8.1 Rounding CKrecticwi 

The available rounding directions are: 

- To-nearest. 

■ Upward. 

- Downward. 

■ Toward-zero. 

The rounding direction affects all conversions and arithmetic operations 
except comparison and remednder. Except for conversions between binary 
and decimal (described in Section 4), all operations are computed as if with 
infinite precision and range and then rounded to the destination format 
according to the CLnrent rounding direction. The rounding direction may be 
interrogated and set by the user. 

The default rounding direction is to-nearest. In this direction the 
representable value nearest to the infinitely precise result is delivered; if the 
two nearest representable values are equally near, the one with least 
significant bit zero is delivered. Hence, halfway cases round to even when 
the d^tination is the comp or a system-specific integer type, and when the 
round-to-integer operation is used. If the magnitude of the infinitely precise 
result exceeds the format's largest value (by at least one half unit in the 
last place), then the corresponding signed infinity is delivered. 

The other rounding directions are upward, downward, and toward-zero. When 
rounding upward, the result is the format's value (possibly INF) closest to and 
no less than the infinitely precise result. When rounding downward, the 
result is the format's value (possibly -INF) closest to and no greater than the 
infinitely precise result. When rounding toward zero, the result is the 
format's value closest to and no greater in magnitude than the infinitely 
precise result- To truncate a number to an integral value, use toward-zero 
rounding either with conversion into an integer format or with the 
round-to-integer operation. 

8.2 Rounding Precision 

Normally, SANE arithmetic computations produce results to extended 
precision and range. To facilitate simulations of arithmetic systems that are 
not extended-based, the IEEE Standard requires that the user be able to set 
the rounding precision to single or double. If the SANE user sets rounding 
precision to single (or double) then all arithmetic operations produce results 
that are correctly rounded and that overflow or underflow as if the 
destination were single (or double), even though results are typically deliv^ed 
to extended formats. Conversions to double and extended formats are 



1-22 



The Standard f^pple Numeric Eiwironmeni S/^NE 



aftected if rounding precision is set to single^ and conversions to extended 
formats are affected if rounding precision is set to double; conversions to 
decimal, comp, and system-specific integer types are not affected by the 
rounding precision. Rounding precision can be interrogated as well as set. 

Setting rounding precision to single or double does not significantly enhance 
performance, and in some SANE implementations may hinder performance. 

83 Exception Flags and Halts 

SANE supports five exception flags with corresponding halt settings: 

- Invalid-operation (or invalid, for short). 

- Underflow. 

- Overflow. 

■ Divide-by-zero. 
• Inexact. 

These exceptions are signaled when detected; and, if the corresponding halt 
is enabled, the SANE engine will jump to a LKer-specified location. (A 
high-level language need not pass on to its user the facility to set this 
location, but may halt the user's program). The user's program can examine 
or set individual exception flags and halts, and can save and get the entire 
environment (rounding direction, rounding precision, exception flags, and halt 
settings). Further details of the halt (trap) mechanism are SANE 
implementation specific. 

8.3.1 Exceptions 

The i/n^aM-operatlm exception is signaled if an operand is invalid for the 
operation to be performed. The result is a quiet NaN, provided the 
destination format is single, double, extended, or comp. The invalid 
conditions are these: 

- (addition or subtraction) magnitude subtraction of infinities, for example, 
(+INF) + (-INF). 

■ (multiplication) * INF. 

- (division) 0/0 or INF/INF. 

- (remainder) x rem y, where y is zero or x is infinite. 

■ (square root) if the operand is less than zero. 

■ (conversion) to the comp format or to a system-specific integer format 
when excessive magnitude, infinity, or NaN precludes a faithful 
representation in that format (see Section 4 for details). 

■ (comparison) via predicates involving < or >, but not "unordered," when 
at least one operand is a NaN. 

- Any operation on a signaling NaN except sign manipulations (negate, 
absolute-value, and copy-sign) and class and sign inquiries. 
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The underflow exception is signaled when a floating-point result is both tiny 
and inexact (and therefore^ perhaps significantly less accurate than it would 
be if the exponent range were unbounded). A result is considered tiny if^ 
before rounding, its magnitude is smaller than its format's smallest positive 
normalized number. 

The dmde-ty-z&ro exception is signaled when a finite nonzero number is 
divided by zero. It is also signaled^ in the more general case, when an 
operation on finite operands produces an exact infinite result: for example, 
logb (0) returns -INF and signals divide-by-zero. (Overflow, rather than 
divide-by-zero, flags the production of an inexact infinite result.) 

The overflow exception is signaled when a floating-point destination 
format's largest finite number is exceeded in magnitude by whet would have 
been the rounded floating-point result were the exponent range unbounded. 
(Invalid, rather than overflow^ flags the production of an out-of -range value 
for an integral destination format.) 

The inexact exception is signaled if the rounded result of an operation is 
not identical to the mathematical (exact) result. Thus, inexact is always 
signaled in conjunction with overflow or underflow. 

Valid operations on infinities are always exact ejid therefore signal no 
exceptions. Invalid operations on infinities are described above. 

8.4 Managing Environmental Settings 

The environmental settings in SANE are global and can be explicitly changed 
by the user. Thus all routines inherit these settings and are capable of 
changing them. Often special precautions must be taken because a routine 
requires certain environment settings, or because a routine's settings are not 
intended to propagate outside the routine. 

Example 1 

The subroutine below uses to-nearest rounding while not affecting its caller's 
rounding direction. (Examples in this section use Pascal syntax. SANE 
implementations in other languages have operations with equivalent 
functionality.) 



var r: RoundDir; { local storage roar rounding direction } 

begin 

r z- GetRound; { saKw caller's rounding direction } 

SetRound (TdCflREST); { set to-nearest rounding } 

SetRound (r) { restore caller's rounding direction } 



end; 
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Note that, if the subroutine is to be reentrant, then storage for the caller's 
environment must be local. 

SANE implementations may prov/ide two efficient functions for managing the 
environment as a whole: procedure-entry and procedure-exit. 

The procedure-entry function returns the current environment (for sawing in 
local storage) and sets the default environment: rounding direction to-nearest, 
rounding precision extended, and exception flags and halts clear. 



Example 2 

The following subroutine runs under the default environment while not 
affecting its caller's environment. 



var e: EnvlTonwnt; { local storage for enMiroraent } 

begin 

ProcEntry (e); { save caller's envimoMsnt and } 

{ set tfefault enMixoriKnt } 

SetEnvlTorMBnt (e) { restore caller's envlrorawnt } 

end^ 

The procedure-exit function facilitates writing subroutines which appear to 
their callers to be atomic operations (such as addition, scfrt, and others). 
(Atomic operations pass extra information back to their callers by signaling 
exceptions; however, they hide internal exceptions, which may be irrelevant 
or misleading. Procedure-exit, which takes a se^/ed environment as 
arguments, does the following: 

1. It temporarily saves the exception flags (raised by the subroutine). 

2. It restores the environment received as argument. 

3. It signals the temporarily saved exceptions. (If enabled, halts could 
occur at this step.) 

Thus exceptions signaled between procedure-entry and procedure-exit are 
hidcten from the calling program unless the exceptions remain raised when 
the procedure-exit function is called. 
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Exemple J 

The following function signals underflow if its result is denormal^ and 
overflow if its result is infinite, but hides spurious exceptions occurring from 
internal computations. 



fiffK^tion canfxres: double;; 

vaor 6: Em/iroment; 
c: NmClass; 

begin {cfmpres} 
Rr«£ntiy (e); 



{ local stor^e for enviroment } 
{ for class inquiry } 



j save caller's enviroment and } 
{ set defoilt envirorament - } 
{ now halts ftLsabl»l } 



conpores := result; { result to be returned } 

c := ClassD (result); { class inquiry } 

ClearXcps; { clear (Missibly spurious exceptions } 

{ now raise sp^ified exception flags: } 

if c « INFINITE then SetException (OVERFLOli TRUE) 
else if c » iSENDRMALJiJM then SetException (INDERFLOH, TRJE); 



ProcExit (e) 



end {conpres} 



{ restore caller's erndroment^ 
{ including any halt enables, and 
{ then siipial exceptions from 
{ siAoroutine 
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9 Auxiliary Procedures 

SANE includes a set of special routines- 
negate^ 

absolute value, 
copy-sign, 
next-after, 
scalb, 
logb, 

—which are recommended in an appendix to the IEEE Standard as aids to 
programming. 

9.1 Sign ManipuMion 

The sign manipulation operations change only the sign of their argument. 
Negate reverses the sign of its argument. Absolute-value makes the sign of 
its argument positive. Copy-sign takes two arguments and copies the sign of 
one of its arguments onto the sign of its other aorgument. 

These operations are treated as nonarithmetic in the sense that they raise no 
exceptions: even signaling NaNs do not signal the invalid-operation exception. 

92. Next-ATter Functiofis 

The floating-point values representable in single, double, and extended 
formats constitute a finite set of real numbers. The next-after functions 
(one for each of these formats) generate the next representable neighbor in 
the proper format, given an initial value x and another value y indicating a 
direction from the initial value. 

Each of the next-after functions takes two arguments, x and y: 

nextsingle(x,y) (x and y are single) 
nextdoubl^x,y) (x and y are double) 
nextextended(x,y) (x and y are extended) 

As elsewhere, the names of the functions may vary with the implementation. 

9JZ.1 Special Cases for Next-After Functions 

If the initial value and the direction value are equal, then the result is the 
initial value. 

If the initial value is finite but the next representable number is infinite, 
then overflow and inexact are signaled. 

If the next representable number lies strictly between -M and 4M, where M 
is the smallest positive normalized number for that format, and if the 
arguments are not equal, then underflow and inexact are signaled. 
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93 Binary Scale and Log Functions 

The scalb and logb functions are provided for manipulating binary exponents. 

Scalb efficiently scales a given number (x) by a given integer power (n) of 2, 
returning x * 2". 

Logb returns the binary exponent of its input argument as a signed integral 
value. When the input argument is denormalized^ the exponent is determined 
as if the input argument had first been normalized. 

93.1 Special Cases for Logb 

If X is infinite, logb(x) returns +INF. 

If X = 0, logb(x) returns -INF and signals divide-by-zero. 
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10 The Elementary Functions 

SANE provides a number of basic mathematical functions, including 
logarithms, exponentials, two important financial functions, trigonometric 
functions, and a random number generator. These functions are computed 
using the basic SANE arithmetic heretofore described. 

All of the elementary functions, except the random number generator, handle 
NaNs, overflow, and underflow appropriately. All signal inexact 
appropriately, except that the general exponential and the financial functions 
may conservatively signal inexact when determining exactness would be too 
costly. 

10.1 Logarithm Functions 

SANE provides three logarithm functions. 



base-2 logarithm 


log2(x) 


base-e or natural 
logarithm : 


ln(x) 


base-e logarithm of 
1 plus argument 


Inl(x) 



Lnl(x) accurately computes ln(l + x). If the input argument x is small, such 
as an interest rate, the computation of lnl(x) is more accurate than the 
straightforward computation of ln(l + x) by adding x to 1 and taking the 
natural logarithm of the result. 

10.1.1 Special Cases for Logarithm Functions 

If x = +INF, then loggCx), ln(x), and lnl(x) return tlNF. No exception is 
signaled. 

If X = 0, then log2(x) and ln(x) return -INF and signal divide-by-zero. 
Similarly, if x = -1, then Inl(x) returns -INF and signals divide-by-zero. 

If X < 0, then log2(x) and ln(x) return a NaN and signal invalid. Similarly, if 
X < -1, then lnl(x) returns a NaN and signals invalid. 

10J2 ExpcNicmtial Functions 

SANE provides five exponential functions. 

- base-2 exponential 2^ 

- base-e or natural 
exponential e>= 

- base-e exponential 
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minus 1 : expl(x) 

- integer exponential x^ (i of integer type) 

- general exponential : xy 

Expl(x) accurately computes & - 1. If the input argument x is small^ such 
as an interest rate^ then the computation of expl(x) is more accurate than 
the straightforward computation of e*^ - 1 by exponentiation and suistraction. 

iOJ2.1 Special Cases fcr 2^, e^ e!xp](x) 

If X = +INF, then 2^, ^, and expl(x) return +INF. No exception is signaled. 

If X = -INF, then 2^ and e'^ retiirn 0; and expl(x) returns -1. No exception is 
signaled. 

10J2.2 Special Cases for x^ 

If the integer exponent i equals and x is not a NaN, then x^ returns 1. 
Note that with the integer exponential, x^ = 1 even if x is zero or infinite. 

If X is +0 and i is negative, then x^ returns +INF and signals divide-by-zero. 

If X is -0 and i is negative, then x^ returns +INF if i is even, or -INF if i is 
odd: both cases signal divide-by-zero. 

10.23 Special Cases for ySf 

If X is +0 and y is negative, then the general exponential xy returns +INF and 
signals divide-by-zero. 

If X is -0 and y is integral and negative, then xV returns +INF if y is even, 
or -INF if y is odd; both cases signal divide-by-zero. 

The general exponential xV returns a NaN and signals invalid if 

both x and y equal 0; 

X is infinite and y equals 0; 

X = 1 and y is infinite; or 

X is -0 or less than and y is nonintegral. 

103 Financial Functions 

SANE provides two functions, compound and annuity, that can be used to 
solve various financial, or time-value-of -money, problems. 

103.1 Compound 

The compound function computes 

cc»npound(r, n) = (1 + r)" 
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where r is the interest rate and n is the number (perhaps nonintegral) of 
periods. When the rate r is small^ compound gives a more accurate 
computation than does the straightforward computation of (1 + r)n by addition 
and exponentiation. 

Compound is directly applicable to computation of present and future values.- 

PV 

W = FV ♦ (1 + r)<-n) = 

compound(r, n) 

FV = PV*(l + r)n =PV* compounder, n) 

103.2 Special Cases for Compounder^) 

If r = and n is infinite, or if r = -1, then compounc(r,n) returns a NaN and 
signals invalid. 

If r = -1 and n < 0, then compound(r,n) returns +INF and signals 
divide-by-zero, 

1033 Anmjity 

The annuity function computes 

1 - (1 + r)<-"> 
annul ty(r, n) « 

r 

where r is the interest rate and n is the number of periods. Annuity is more 
accurate than the straightforward computation of the expression above using 
basic arithmetic operations and exponentiation. The annuity function is 
directly applicable to the computation of present and future values of 
ordinary annuities.- 

1 - (1 + r)<-n> 
PV = PMT ♦ 

r 

= PMT * annul ty(r, n) 

(1 + r)" - 1 

FV « PMT * 

r 

= PMT * (1 + r)n 

r 
= PMT ♦ compounder, n) * annul ty(r, n) 

where PMT is the amount of one periodic payment. 
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103.4 Special Cases for ^^irHJity(r^ 

If r = 0, then annuity(r,n) computes the sum of 1 + 1 + ... + 1 over n periods, 
and therefore returns the value n and signals no exceptions (the value n 
conesponds to the limit as r approaches 0). 

If r < -1, then annuity(r,n) returns a NaN and signals invalid. 

If r = -1 and n > 0, then annuity(r,n) returns -INF and signals divide-by-zero. 

10.4 Tri^jnomdxic Functions 

SANE provides the basic trigonometric functions: 

cosine : cos(x) 

sine : sin(x) 

tangent : tan(x) 

arctangent : arctan(x) 

The arguments for cosine, sine, and tangent and the results of arctangent are 
expressed in radians. The cosine, sine, and tangent functions use an 
argument reduction based on the remainder function (see Section 3) and the 
nearest extended-precision approximation of pi/2. Thus the cosine, sine, and 
tangent functions have periods slightly different from their mathematical 
counterparts and diverge from their counterparts when their arguments 
become large. Number results from arctangent lie between -pi/2 ajid pi/2. 

The remaining trigonometric functions can be easily and efficiently computed 
from these four (see Appendix C). 

10.4.1 Special Cases for sin(xX cci6(x): 

If X is infinite, then cos(x) and sin(x) return a NaN and signal invalid. 

10.4.2 Special Cases for tan(x>: 

If X is the nearest extended approximation to ±pi/2, then tan(x) returns sINF. 

If x is infinite, then tan(x) returns a NaN and signals invalid. 

10.43 Sp^ual Case for flrctari(x): 

If X = iINF, then arctan(x) returns the nearest extended approximation to 
±pi/2. 
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103 Random Number Generator 

SANE provides a pseudorandom number generator, random. Random has one 
argument, passed by address. A sequence of (pseudo)random integral values r 
in the range 

1 < r < 231 - 2 

can be generated by initializing an extended variable r to an integral value 
(the seed) in the above range and making repeated calls random (r); each call 
delivers in r the next random number in the sequence. 

If seed values of r are nonintegral or outside the range 
1 i r < 231 - 2 

then results are unspecified. 

A pseudorandom rectangular distribution on the interval (0,1) can be obtained 
by dividing the results from random by 

231-1 = scalb (31,1) - 1 . 
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AppencBxB 
OLossary 



applicflUon type: f\ data type used to store data for applications. 

arithmetic ty^e-. A data type used to hold results of calculations inside the 
computer. The SfiNE arithmetic type^ extended, has greater range and 
precision than the 8f)plication types, in order to improve the mathematical 
properties of the application types. 

binary rioafcing-imint numiier: f\ string of bits rein^esentlng a sign, an 
exponent, and a significand. Its numerical value, if any, is the signed 
product of the significand and two raised to the power of its exponent. 

comp tvfie: f\ 64--bit application data type for storing integral values of up 
to 18- or i9-decimal-digit precision. It is used for accounting applications, 
among others. 

denormalized number, or denonri: A nonzero binary floating-point number 
that is not normalized (that is, whose significand has a leading bit of zero) 
and whose exponent is the minimum exponent for the number's storage type. 

double type: A 64-bit application data type for storing floating-point values 
of up to 15- or 16-decimal-digit precision. It is used for statistical and 
financial applications, among others. 

enK/ironmental settings: The rounding direction and rounding precision, plus 
the exception flags and their respective halts. 

excepticms: Special cases, specified by the IEEE Standard, in arithmetic 
operations. The exceptions are invalid, underflow, overflow, divide-by-zero, 
and inexact. 

exception flag: Each exception has a flag that can be set, cleared and 
tested. It is set when its respective exception occurs and stays set until 
explicitly cleared. 

exponent: The part of a binary floating-point number that indicates the 
power to which two is raised in determining the value of the number. The 
wider the exponent field in a numeric type, the greater range it will handle. 

extended type: An 80-bit arithmetic data type for storing floating-point 
values of up to 19- or 20-decimal-dlgit precision. SANE uses it to hold the 
results of arithmetic operations. 
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halt: Each exception has a halt-enable that can be set or cleared. When an 
exception is signaled and the corresponding halt is enabled, the SANE engine 
will transfer control to the address in a halt vector. A high-level language 
need not pass on to its user the facility to get the halt vector, but may halt 
the user's program. Halts remain set until explicitly cleared. 

infinity: A special bit pattern produced when a floating-point operation 
attempts to produce a number greater in magnitude than the largest 
representable number in a given format. Infinities are signed. 

integes- tyF»s: System types for integral values. Integer types typically use 
16- or 32-bit two's complement integers. Integer types are not SAME types 
but are available to SANE users. 

integral value: A value in a SANE type that is exactly equal to a 
mathematical integer: ..., -2, -1, 0, 1, 2, .... 

NaN (Not a IshJinber): A special bit pattern produced when a floating-point 
operation cannot produce a meaningful result (for example, 0/0 produces a 
NaN). NaNs can also be used for uninitialized storage. NaNs propagate 
through arithmetic operations. 

ncrmalized nunriier: A binary floating-point number in which all significand 
bits are significant: that is, the leading bit of the significand is 1. 

quiet NaN: A NaN that propagates through arithmetic operations without 
signaling on exception (and hence without halting a program). 

rounding direction: When the result of an arithmetic operation cannot be 
represented exactly in a SANE type, the computer must decide how to round 
the result. Under SANE, the computer resolves rounding decisions in one of 
four directions, chosen by the user: to-nearest (the default), upward, 
downward, and toward-zero. 

sign bit: The bit of a single, double, comp, or extended number that 
indicates the number's sign: indicates a positive number; 1, a negative 
number. 

signaling NaKk A NaN that signals an invalid exception when the NaN is s^ 
operand of an arithmetic operation. If no halt occurs, a quiet NaN is 
produced for the result. No SANE operation creates signaling NaNs. 

sigrrificand: The part of a binary floating-point number that indicates where 
the number falls b^ween two successive powers of two. The wider the 
significand field in a numeric type, the more resolution it will have. 

single type: A 32-bit application data type for storing floating-point values 
of up to 7- or 8-decimal-digit precision. It is used fcMr engineering 
applications, among others. 
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Appendix C 
Other Elementary Functions 



High quality transcendental functions which are not part of the Standard 
Apple Numeric Environment (SANE) can be constructed from the functions 
which SANE provides. Some common functions are provided below in 
pseudo-code. It should be relatively easy to adapt them for your use. 

These functions are based on algorithms developed by Professor William 
Kahan, University of California at Berkeley. They are robust and accurate. 
The constant C is 2-^^ = scalb (-33,1). It is chosen to be nearly the largest 
value for which (1 - C^) rounds to 1. All variables are extended. 

Exception l-tandling 

Unlike the SANE elementary functions, these functions do not provide 
complete handling of special-cases and exceptions. The most troublesome 
exceptions can be correctly handled if you: 

- Begin each function with a call to procedure-entry. 

■ Clear the spurious exceptions indicated. 

■ End each function with a call to procedure-exit (see Section 8). 

Functions 

Secant 

sec(x) < — 1 / cos(x) 
CoSecant 

csc(x) < — 1 / sin(x) 
CoTangent 

cot(x) < — 1 / tan(x) 
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ftrcSine 



y <— |x| 

If y 2 0.3 then begin 

y < — fttan (x/scprt ((l-x)*(l+x))) 
spurious divide-by-zero iney arise 
end 
else if y 2 C then y < — fttan (x / (scprt (1 - x^2)) 

else y < — x 
arcsin(x) < — y 



ftrcCosine 



arccos(x) < — 2 * fttan (sqrt ((l-x)/(l+x)) ) 
spurious divide-by-zero may arise 



Sinh 



y < — |x| 

If y 2 C then begin 

y < — expl(y) 

y < — 0.5 ♦ (y + y/(l-^y)) 
end 
copy the sign of x onto y 
sinh(x) < — y 



Cosh 



y < — exp(|x|) 

cosh(x) < — 0.5 * y + 0.25 / (0.5 * y) 



Tanh 



y < — |xl 

If y 2 C then begin 

y < — expl(-2*y) 

y < y/(2 + y) 

end 

copy the sign of x onto y 

tanh(x) < — y 
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ftrcSinh 

y < — |x| 

If y 2 C then begin 

y < — Inl (y + y / (1/V + scprt(l + (l/y)*2) )) 
spurious underflow may arise 
end 
copy the sign of x onto y 
asinh(x) < — y 

ftrcCosh 

y < — |x| 

acosh(x) < — Inl ( (sqrt (y-1)) ♦ (scprt (y-1) + scprt (y+1)) ) 

ftrcTanh 

y < — |x| 

If y 2 C then y < — Inl (2*y/<l - y)) / 2 

copy the sign of x onto y 

atanh(x) < — y 
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Introduction 

The purpose of the software package described in this manual is to provide 
the features of the Standard Apple Nunr^eric Environment (SANE) to 
assembly-language programmers on Apple's 68000-based systems. 
SANE— described in detail in The Stancfarcf f^ple Numeric Em^ironment in 
this binder— fully supports the IEEE Standard (754) for Binary Floating-Point 
Arithmetic; it augments the Standard to provide greater utility for 
applications in accounting, finance, science, and engineering. The IEEE 
Standard and SANE offer a combination of quality, predictability, and 
portability heretofore unknown for numerical software. 

A functionally equivalent 6502 assembly-language SANE engine is available 
for Apple's 6502-based systems. Thus numerical algorithms coded in 
assembly language for an Apple 68000-based system can be readily receded 
for an Apple 6502-based system. Suggested macros for accessing the 6502 
and 68000 engines have been chosen to further facilitate algorithm 
portability. 

This manual describes the use of the 68000 Assembly-Language SANE engine, 
but does not describe SANE itself. For example, this manual explains how to 
call the SANE remainder function from 66K)00 assembly language but does not 
discuss what this function does. See The Standsard tipple Num&ric 
ErKfironmentT fac information about the semantics of SANE. 

See Appendix A for information about accessing the 68000 SANE engine from 
the Apple 6%XX)-based systems. 
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2 Basics 

The following code illustrates a typical invocation of the SANE engine^ 
FP68K. 

FEA A_flDR ; Push address of A (single foxnat) 

PEA B_ff3R ; Push address of B (extended fornat] 

FSUBS ; Floating-point SLJBtxact Single: B < — B - ft 

FSUBS is an assembly-language macro taken from the file listed in Appendix 
B. The form of the operation in the example (B <~ B - A, where A is a 
numeric type and B is extended) is similar to the fornns for most FP68K 
operations. Also, this example is typical of SANE engine calls because 
operands are passed to FP68K by pushing the addresses of the operands onto 
the stack prior to the call. Details of SANE engine access are given later in 
this section. 

The SANE elementary functions are provided in Elems68K. Access to 
Elems68K is similar to access to FP86K; details are given in Section 9. 

2.1 OperaticNn Forms 

The example above illustrates the form of an FP68K binary operation. Forms 
for other FP68K operations are described in this section. Examples and 
further details are given in subsequent sections. 

2.1.1 AritNiwtic and f^xiliary Operations 

Most numeric operations are either unary (one operand), like square root and 
negation, or binary (two operands), like addition and multiplication. 

The 6&D00 assembly-language SANE engine, FP68K, provides unary operations 
in a one-address form: 

DST <— <op> DST ... for example, B <— sqrt(B) 

The operation <op> is applied to (or operates on) the operand DST and the 
result is returned to DST, overwriting the previous value. DST is called the 
destination operand. 

FP58K provides binary operations in a two-address form: 

DST <~ DST <op> SRC ... for example, B <~ B / ft 

The operation <op> is applied to the operands DST and SRC and the result is 
returned to DST, overwriting the previous value. SRC is called the source 
operand. 

In order to store the result of an operation (unary or binary), the location of 
the operand DST must be known to FP68K, so DST is passed by address to 
FP68K. In general all operands, source and destination, are passed by 
address to FP68K. 
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For most operations the storage format for a source operand (SRC) can be 
one of the SANE numeric formats (single, double, extended, or comp). To 
support the extended-based SANE arithmetic, a destination operand (DST) 
must be in the extended format. 

The forms for the copy-sign next-after functions are unusual and will be 
discussed in Section 4. 

2.1.2 CxwwGtsions 

FP68K provides conversions between the extended format and other SANE 
formats, between extended and 16- or 32-bit integers, and between extended 
and decimal records. Conversions between binary formats (single, double, 
extended, comp, and integer) and conversions from decimal to binary have 
the form 

DST <— SRC 

Conversions from binary to decimal have the form 

DST <~ SRC according to SRC2 

where SRC2 is a DecForm record specifying the decimal format for the 
conversion of SRC to DST. 

2.13 Comparisons 

Comparisons have the form 

<relation> <~ SRC, DST 

where DST is extended and SRC is single, double, comp, or extended, and 
where <r elation > is less, equal, greater, or unordered according as 

DST <relation> SRC 

Here the result <relation> is indicated by setting the 68CXX) CCR flags. 

2.1.4 Other Operations 

FP68K provides inquiries for determining the class and sign of an operand 
and operations for accessing the floating-point environment word and the halt 
address. Forms for these operations vary and will be given as the operations 
are introduced. 

2J2 External Access 

The SANE engine, FP68K, is reentrant, position-independent code, which may 
be shared in multi-process environments. It is accessed through one entry 
point, labeled FP68K. Each user process has a static state area consisting of 
one word of mode bits and error flags, and a two-word halt vector. The 
package alloss^ for different access to the state word in single and 
multi-process environments. 

The package preserves all 68000 registers across invocations, except that 
REMAINDER modifies DO. The package modifies the 68000 CCR flags. 
Except for binary-decimal conversions, it uses little more stack area than is 
required to save the sixteen 32-bit 68000 registers. Since the binary-decimal 
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conversions themselves call the package (to perform multiplies and divides), 
they use about twice the stack space of the regular operations. 

The access constraints described in this section also apply to Elems68K. 

23 Calling Sequeaice 

A typical invocation of the engine consists of a sequence of PEA's to push 
operand addresses followed by one of the Appendix 6 macros: 

PEA < source address) 

PEfl < destination address) 
<FOPMACRO> 

PEA'S for source operands always precede those for destination operands. 

<FOPMACRO) represents a typical operation macro defined as 

MWE.H <o|Mord>,-(SP) ; Push op code. 

JSRFP 

The macro JSRFP in turn generates a call to FP68K; for Macintosh, it 
expands to an A-line trap, while for Lisa it expands to an intrinsic unit 
subroutine call 

J5R FPeaK 

23.1 The Opvrard 

The opword is the logical OR of a operand format code and an operation 
code. 

The operaaid format code specifies the format (extended, double, single, 
integer, or comp) of one of the operands. The operand format code typically 
gives the format for the source operand (SRC). At most one operand format 
need be specified, since other operands' formats are implied. 

The operation code specifies the operation to be performed by FP68K. 

Opwords are listed in Appendix C; operand format codes and operation codes 
are listed in Appendix B. 

ExampJe 

The format code for single is 02CX) (hex). The operation code Tar divide is 
0006 (hex). Hence the opword 0206 (hex) indicates divide by a value of type 
single. 

23J2 ^^sserrAly-Lar^jai^ Macros 

The macro file in Appendix B prwides macros for 

MOVE.W < opword ), -(SP) 
JSRFP 

for most common <opword) calls to FP68K. 
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Example 1 

To add a single-format operand A to an extended-format operand B, simply 
write: 

PEA A.flOR ; Push address of A 

PEA B_flDR ; Push address of B 

ffDOS J Floating-point fliX) Single-. B < — B + A 

Ex&mple 2 

Compute B < — scjrt^A), where A and B are extended. The value of A should 
be preserved. 

PEA A.flDR ; Push address of A 

PEA B.flDR ; Push address of B 

FX2X ; Floating-point extended to (iterated: B < — A 

PEA B_flDR ; Push address of B 

FSQRTX ; Floating SOuare RooT ^tended: B <— sqrt(B) 

Example J 

Compute C <~ A - B, where A, B, and C are in the double format. Since 
destinations are extended^ a temporary extended variable T is required. 

PEA A_ADR ; Push address of A 

PEA T_flDR ; Push address of 10-b^e temporary variola 

FD2X ; Fl-pt convert Double to ^tended: T < — A 

PEA B_ADR ; Push address of B 

PEA T_flDR ; FHish address of teaporary 

P5LBD ; Fl-pt SUBtract Double: T < — T - B 

PEA T_flDR ; Push adkiress of tenporary 

PEA CJ>DR ; Push address of C 

FX2D ; Fl-pt convert extended to Double: C < — 

2.4 Arithmetic Abuse 

FP68K is designed to be as robust as possible, but it is not bulletproof. 
Passing the wrong number of operands to the engine will damage the stack. 
Using UNDEFINED opword parameters or passing incorrect addresses will 
produce undefined results. 
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3 Data Types 

FP6BK fully supports the SANE data types 

single — 32-bit floating-point 

double — 64-bit floating-point 

comp — 64-bit integer 

extended — «>-bit floating-point 

and the 68000-specif ic types 

integer — 16-bit two's complement integer 
longint — 32-bit two's complement integer 

The 6©D00 engine uses the convention that least-significant bytes are stored 
in high memory. For example, let us take a variable of type single with bits 

s — sign 

eO ... e7 — exponent (msb...lsb) 

fO ... f22 — significand fraction (msb...lsb) 

The logical structure of this four-byte variable is shown below: 

rnsb Isb msb Isb order 



s|el Mill |e|f| i I I I I II I II II I i I I i II llfl 
|0| I I i i I iOlOi I I I II i I I i i I I I I I I I i I I I2| 
|0| I I I I I |7|0| I I I i I I I I I I i I I I I I I i I I I2i 



1000 1001 1002 1003 

If this variable is assigned the adch-ess 1(XX>, then its bits are distributed to 
the locations 1000 to 1(X)3 as shown. The other SANE formats (see Section 
2 in The Stencfard ^pple Numeric Em-'ironment^ are represented in memory in 
similar fashion. 
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A i^Mthmetic Operafcions and Auxiliary Routines 

The operations covered in this section follow the access schemes described 
in Section 2. 

unary operations.- DST < — <op> DST (one- address form) 

PEfl <DST address > 

<FOPMACRO> 

binary operations: DST < — DST <op> SRC (two-address form) 

PEft <SRC address) 

PEft <DST address) 

<FXFMACRO> 

The destination operand (DST) for these operations is passed by address and 
is generally in the extended fornnat. The source operand (SRC) is also passed 
by address and may be single, double, comp, or extended. Some operations 
are distinguished by requiring some specific type for SRC, by using a 
nonextended destination, or by returning auxiliary information in the CX) 
register and in the processor CCR status bits. In this section, operations so 
distinguished are noted. The examples employ the macros in Appendix B. 

4.1 Adit Subtract, Multiply, and Divide 

These are binsory operations and follow the two-address form. 

Example 

B < — B / A , where A is double and B Is extended: 

PEA A.flOR ; push address of A 
PEA B_ADR ; push address of B 
FDIVD ; divitfe iflth scMirce operand of type doiAile 

A2. Square Root 

This is a unary operation and follows the one-address form. 

Exemple 

B <~ scp:t(B) , where B is extended. 

PEA B_fl[3R ; push address of B 

FSfSRTX ; square root (operand is always extended) 

43 Round-to-integer, Truncate-to-Integer 

These are unary operations and follow the one-address form. 

Round-to-integer rounds (according to the current rounding direction) to an 
integral value in the extended format. Truncate-to-integer rounds toward 
zero (regardless of the current rounding direction) to an integral value in the 
extended format. The calling sequence is the usual one for unary operators, 
illustrated above for square root. 
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4.4 Remainder 

This is a binary op^abion and follows the two-address form. 

Remainder returns auxiliary information: the low-order integer quotient 
(between -127 and +127) in DO.W. The high half of DO.L is undefined. This 
intrusion into the register file is extremely valuable in argument 
reduction— the principal use of the remainder function. The state of CX> 
after an invalid remainder is undefined. 

Example 

B < — B rem ft , where ft is single and B is extended. 

PEA A_flDR ; push addtess of A 

FEA B_flOR ; push address of B 
FREMS ; Teamnkir with scNirce operaml of type single 

43 Locjb, Scalb 

Logb is a unary operation and follows the one-address form. 

Scalb is a binary operation and follows the two-address form. Its source 
operand is a 16-bit integer. 

Example 

B <~ B * 2\ where B is extended. 

PEA I_ADR ; push address of I 
PEA B_flDR ; push address of B 
FSCALfiX ; scalb 

4.6 KJegcte, Absolute VaLuB, Cc^-Sign 

Negate and absolute value are unary operations and follow the one-address 
form. 

Copy-sign uses the calling sequence 

PEft <SRC address > 

PEA <DST address) 

FCPYSGNX 

to copy the sign of DST onto the sign of SRC. Note that copy-sign differs 
from most two-address operations in that it changes the SRC value rather 
than the DST value. The formats of the operands for FCPYSGNX can be 
single, double, or extended. (For efficiency, the 680CX) assembly-language 
programmer should copy signs directly rather than call FP68K.) 
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Example 

Copy the sign of B (single, double, or extended) into the sign of A (single, 
double, or extended). 

PEA ajOR ; FHJsh adUress of A 

PEA B_ADR ; push address of B 
FCPYSGNX ; copy-sign 

4.7 Isiext-Arter 

The next -after operations use the calling sequence 

PEft <SRC address > 

PEA <DST address) 

<next-after macro) 

to effect SRC <— next value, in the format indicated b/ the macro, after 
SRC in the dirction of DST. Next-after operations differ from most 
two-address operations in that they change SRC values rather than DST 
values. Both source and destination operands must be of the same 
floating-point type (single, double, or extended). 

Exemple 

A <— next-after(A) in the direction of B, where A and B are double (so 
next-eftm^ means next-double-stter ). 

PEA A.flDR ; push address of A 

PEA B_ADR ; push address of B 
ROOD ; next-after in double foonat 
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5 Conversions 

This section discloses conversions between binary formats and conversions 
between binary and decimal formats. 

5.1 ConMorsions Between Binary Formalts 

FP68K provides conversions between the extended type and the SANE types 
single, double, and comp, as well as the 16- and 32-bit integer types. 

5.1.1 Conversions to Extended 

FP68K provides conversions of a source, of type single, double, comp, 
extended, or integer, to an extended destination. 

single 
double 
extended < — corap 

extended 
integer 

All operands, even integer ones, are passed by address. The following 
example illustrates the calling sequence. 

Example 

Convert A to B, where A is of type comp and B is extended. 

PEA fl_flDR ; push address of A 
PEA B_flDR ; push address of B 

FC2X ; cwff/ert conp to extended 

5.1J2 Conversions from Extended 

FP68K provides conversions of an extended source to a destination of type 
single, double, comp, extended, or integer. 

single 

double 

comp < — extended 

extended 

integer 

(Conversion to a narrower format may alter values.) Contrary to the usual 
scheme the destination for these conversions need not be of type extended. 
All operands are passed by address. The following example illustrates the 
calling sequence. 
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Example 

Convert A to B where A is extended and B is double. 

PEA A_ADR ; push address of A 

PEA B.flOR ; push address of B 

FX2D ; convert extended to double 

3.2 Binary-Decimal Conversions 

FP68K provides conversions between the binary types (single, double, comp, 
extended, and integer) and the decimal record type. 

Decimal records and decform records (used to specify the form of decimal 
representations) are described in Section 4 of The Standerd f^pple Numeric 
EmHronment. For FP68K, the maximum length of the sig digits field of a 
decimal record is 20. (The value 20 is specific to this implementation: 
algorithms intended to port to other SANE implementations should use no 
more than 18 digits in sig.) 

3JL1 Binary to Decimal 

The calling sequence for a conversion from a binary format to a decimal 
record passes the address of a decform record, the address of a binary 
source operand, and the address of a decimal-record destination. The 
maximum number of significant digits that will be returned is 19. 

Example 

Convert a comp-format value A to a decimal record D according to the 
decform record F. 

PEA F_flDR ; push address of F 

PEA A_ADR ; push address of A 

PEA D_flDR ; push address of D 

FC2DEC ; convert can|> to decimal 

Fixed-Format "CK''erflow" 

If a numbei" is too large for a chosen fixed style, then FP68K returns the 
string '?' in the sig field of the decimal record. 

5J;.2 Decimal to Binary 

The calling sequence for a conversion from decimal to binary passes the 
address of a decimal-record source operand and the address of a binary 
destination operand. 

The maximum number of digits in sig is 19. If the length of sig is 20, then 
sig represents its first 19 digits plus one or more additional nonzero digits 
after the 19th. The exponent corresponds to the 19-digit integer represented 
by the first 19 digits of sig. 
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Example 

Convert the decimal record D to a double-format value B. 

FEA P_flOR ; push address of D 
PEA B_flDR ; push address of B 
FDBC2D ; convert ttecinal to double 

Techniques for Extreme f^ccuracy 

The following techniques apply to FP68K; other SANE implementations 
require other techniques. 

For maximum accuracy, insert or delete trailing zeros for the sig field of a 
decimal record in order to minimize the magnitude of the exp field. For 
example, for 1.0E60 set sig to '1000000CK)CKX)CW0000000000000' (17 zeros) and 
exp to 43, and for 300E-43 set sig to '3' and exp to -41. 

If you are writing a parser and must handle a number with more than 19 
significant digits, follow these rules: 

■ Place the implicit decimal point to the right of the 19 most significant 
digits. 

■ If any of the discarded digits to the right of the implicit decimal point 
are nonzero, then concatenate the digit '1' to sig. 
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6 Comparisons and Inquiries 

6.1 ComiMrisons 

FP68K offers two comparison operations: FCPX (which signals invalid if its 
operands compare unordered) and FCMP (which does not). Each compares a 
source operand (which may be single, double, extended, or comp) with a 
destination operand (which must be extended). The result of a comparison is 
the relation (less, greater, equal, or unordered) for which 

DST <relation> SRC 

is true. The result is delivered in the X, N, Z, V, and C status bits: 

<relation> Status bits 

X N 2 V C 

greater 

less 110 1 

equal 10 

unordered 10 

These status bit encodings reflect that floating-point comparisons have four 
possible results, unlike the more familiar integer comparisons with three 
possible results. It's not necessary to learn these encodings, however; simply 
use the FBxxx series of macros for branching after FCMP and FCPX. 

FCMP and FCPX are both provided to facilitate implementation of relational 
operators defined by higher level languages that do not contemplate 
unordered comparisons. The IEEE standard specifies that the invalid 
exception shall be signalled whenever necessary to alert users of such 
languages that an unordered comparison may have adversely affected their 
program's logic. 

Ex&mple 1 

Test B <= A, where A is single and B is extended; if TRUE branch to LOC; 
signal if unordered. 

PEA A_flOR ; push address of A 

PEA B.ADR ; push address of B 

FCPXS ; conpare usir^ source of type single, 

; signal invalid if uncxrctered 

FBLE LOC ; kn-anch if B <= A 

Example 2 

Test B not-equal A, where A is double and B is extended; if TRUE branch to 
LOC. (Note that not-equal is equivalent to less, greater, or unordered, so 
invalid should not be signaled on unordered.) 
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PEA ajtUR ; push address of A 

FEA BJDR ; push address of B 

FOHPD ; caiqtare using source of type double, 

; do not signal invalid if UHncxrdtered 

FBNE LDC ; faoranch if B not-equal A 

6J2 Irayuiries 

The classify operation provides both class and sign inquiries. This operation 
takes one source operand (single, double^ or extended), which is passed by 
address, and places the result in a 16-bit integer destination. 

The sign of the result is the sign of the source; the magnitude of the result 
is 



signaling NaN 

quiet NaN 

infinite 

zero 

normal 

denormal 



Example 

Set C to sign and class of A. 



PEA A_flDR 

PEA C_flDR 

PCLASSS 



push address of A 
push address of result 
classify single 



1-14 



The 680C>0 Sf^NE Engine The 68000 St^NE Engine 



7 Ens/jronmentol C^ontrol 

7.1 The EnviroiiiTM»it ViatSi 

The floating-point environment is encoded in the 16-bit integer format as 
shown below in hexadecimal: 

rmsb Isb 
I 1 1 

I-|rIrlxld|o|u|i|-|R|RlX|D|OiU|I| 



rounding exception rounding halt 

direction flags precision enables 

rounding direction, bits 6(XX) rr 

0000 — to-nearest 
2000 ~ upward 
4000 — downward 
60(X) — toward-zero 

exception flags, bits IFOO 

0100 ~ invalid i 

0200 ~ underflow u 

0400 ~ overflw o 

0800 — division-by-zero d 

1000 — inexact x 

rounding precision, bits 0060 f^ 

0000 ~ extended 
0020 — double 
0040 ~ single 
0060 ~ UhDEFIhED 

halt enabled, bits OOIF 

0001 ~ invalid I 

0002 ~ underflow U 
0004 ~ overflow 
<XX)8 — division-by-zero D 
0010 ~ inexact X 

Bits 8000 and 0080 are undefined. 

Note that the default environment is represented by the integer value zero. 
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Example 

With rounding toward-zero^ inexact and underflow exception flags raised, 
extended rounding precision, ^ars^ halt on invalid, overflow, and 
division-by-zero, the most significant byte of the environnnent is 72 afid the 
least significant byte is OD. 

Access to the environment is via the operations get-environment, 
set-environment, test-exception, set-exception, procedure-entry, and 
procedure-exit. 

72. Get-EriMircmmenfc and Set-ErM/ironment 

Get-Em-ijronnrtent takes one input operand: the address of a 16-bit intego' 
destination. The environment word is returned in the destination. 

Set-Environment has one input operand.- the address of a 16-bit integer, 
which is to be interpreted as an environment word. 

Exemple 

Set rounding direction to toward-zero. 

PEft fiJOR 

FGETENV 

ICME.M (flO),00 ; 00 gets enviToment 

OR.W #$6000, DO ; set rounding toword-zero 

HDVE.W DO, (flO) ; restcnre A 

PEft ft_flDR 

FSETEHV 

73 Test-Exception and Set-Exception 

Test-exception has one integer destination operand, which contains the hex 
values 

01 ~ invalid 

02 — underflow 
04 — overflow 

08 — divide-by-zero 
10 — inexact 

If the exception flag is set for the corresponding bit in the operand, then 
test-exception sets the destination to $1<X), otherwise, to zero. 

Set-exception takes one integer source operand, which encodes an exception 
in the manner described above for test-exception. Set-exception stimulates 
the exception indicated in the operand. 

7.4 Procedure-Enbry and Procedure-Exit 

Procedure-entry saves the current floating-point environment (15-bit integer) 
at the address passed as the sole operand, and sets the operative 
environment to the default state. 
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Procedure-exit sawes (temporarily) the exception flags, sets the environment 
passed as the sole operand, and then stimulates the saved exceptions. 

Ex&mple 

Here is a procedure that appears to its callers as an atomic operation. 

AimiCPRX 

PEfl E.flDR ; push address to store envlroriMsnt 
FPRDCENTRY ; procedure entzy 

. . .body of routine. . . 

PEft E_flDR ; push address of enKdroraent 
FPROCEXIT ; procedure exit 

RTS 
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8 Halts 

FP68K provides the facility to transfer program control when selected 
floating-point exceptions occior. Since this facility will be used to 
implement halts in high-level languages, we refer to it as a halting 
mechanism. The assembly-language programmer can write a 'halt handler' 
routine to cause special actions for floating-point exceptions. The FP68K 
halting mechanism differs from the traps that are an optional part of the 
IEEE Standard. 

8.1 Conditions for a Halt 

Any floating-point exception can^ under the appropriate conditions, trigger a 
halt. The halt for a particular exception is enabled when the user has set 
the halt-enable bit corresponding to that exception. 

8.2 The Halt Mechanism 

If the halt for a given exception is enabled, FP68K does these things when 
that exception occurs: 

1. FP68K returns the same result to the destination address that it would 
return if the halt were not enabled. 

2. It sets up the following stack frame: 

tqs-of-stack ~> I \ fl word containing the opcode. 

I 1 ft long word containing DST address. 



J fl long word containing 9RC address. 



J fl long word containing SRC2 address. 



I 1 fl long word pointing to Mia:. 

MISC is a reccMTd consisting of: 

fil^: i I ft word containing halt exceptions. 

\ I ft word containing pending OCR. 



J A long word containing pending DO. 



The first word of MISC contains in its five low-order bits the AND of the 
halt-enable bits with the exceptions that occurred in the operation just 
completing. If halts were not enabled, then (upon return from FP68K) CCR 
and DO would have the values given in MISC. 
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3. It passes control b^ JSR thirough the halt vector previously set by 
FSETHV, pushing another long word containing a return address in 
FP68K. If execution is to continue, the halt procedure must clear 
eiqhteen bytes from the stack to remove the opword and the DST, 
SRC, SRC2, and MISC addresses. 

Set -halt -i-ector has one input operand: the address of a 32-bit integer, 
which is interpreted as the halt vector (that is, the address to jump to in 
case a halt occurs). 

Get-haJt-i-'ector has one input operand: the address of a 32-bit integer, 
which receives the halt vector. 

83 Using the Halt Mechanism 

This example illustrates the use of the halting mechanism. The user must 
set the halt vector to the starting address of a halt handler routine. This 
particular halt handler returns control to FP68K which will continue as if no 
halt had occurred, returning to the next instruction in the user's program. 

LEA mOUnrC^M) ; AO gets address of halt routine 

HDVE.L m,HJDR ; HJ£R gets saie 

PEft H_flDR 

F5ETHV ; set halt vector to HRDUTI^E 

PEA ; floating-point t^terand here 

<n]PriACRO> ; a floating-point call here 

mOUTINE ; called by FP68K 

MDVE.L (SP)+,AO ; AO sat^s return address in FPSaC 

ADD.L #18, SP ; increnent stack past argunK»nts 

Jf* (AO) ; return to FPSfiK 

The FP68K halt machanism is designed so that a halt procedure may be 
written in Lisa Pascal. This is the form of a Pascal equivalent to 
HROUTINE: 
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tyr» Riscrec = recordi 

haltearrcirs : integer ; 
ccacT^rHling : integer ; 
DOpendir^ : longint ; 
end {record} ; 

procedure haltrcMJtine 

( var nisc : niscrec ; 
src2, src, dst : IwiQint ; 
opcode : integer ) ; 

tegin {haltroutine} 
end {NsLltroutine} ; 

Like HROUTINE, haltroutine m^ely continues execution as if no halt had 
occurred. 
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9 Elementaiy Functions 

The elementary functions that are specified by the Standard Apple Numeric 
Environment are made available to the 68000 assembly-language programmer 
in ELEMS68K. Also included are two functions that compute 1092(1 +x) and 2* 
- 1 accurately. ELEMS68K calls the SANE engine (FP68K) for its basic 
arithmetic. The access schemes for FP68K (described in Section 2) and 
ELEMS68K are similar. Opwords and sample macros are included at the end 
of the file listed in Appendix B. (These macros will be used freely in the 
examples below.) 

9.1 One-Argunent Functions 

The SANE elementai-y functions log2(x), ln(xX lnl(x) = ln(l+x), 2\ e\ expl(x) = 
ex - 1, cos(x), sir<x), tan(x), atar<x), and random(xX together with log21(x) = 
log2(l+x) and exp2i(x) = 2*^ - 1, each have one extended argument, passed by 
address. These functions use the one-address calling sequence 

PEft DST 

<EOPMACRO> 

to effect 

DST <~ <op> DST 

<EOPMACRO> is one of the macros in appendix B that generate code to push 
an op word and invoke ELEMS68K. This follows the FP68K access scheme 
for unary operations, such ss square root and negate. 

ExempJe 

B <— sin(B), where B is of extended type. 

PEA BJDR ; push address of B 
FSINX ; B <— sin(B) 

92. Two-Argumorit Functions 

General exponentiation (xV) has two extended arguments, both passed by 
address. The result is returned in x. 

Integer exponentiation (x^) also has two arguments. The extended argument. 
X, passed by address, receives the result. The 16-bit integer argument i is 
also passed by address. 

Both exponentiation functions use the calling sequence for binary operations 

PEA SRC addbress ; push exponent address first 
PEA DST address ; pus^ base address seccffid 
<BCIPf1ACnO> 

to effect 

DST <~ DSTSRC 
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Ex&mple 

B <— 0^^ where the type of B is extended. 

PEA K.flOR ; push address of K 
F€A B.flDR ; push address of B 
FXPMRI ; int^er exponentiation 

9.3 Three-f^gprreril; Functions 

Compound and annuity use the calling sequence 

PEA SRC2 address ; push address of rate first 

PEA SRC address ; push aiMress of nunter of periods second 

PEA DGT address ; push address of destinatiofi third 

<EDPHACRO> 

to effect 

DST <— <op> (SRC2, SRC) 

where <op> is compound or annuity, SRC2 is the rate, and SRC is the number 
of periods. All arguments SRC2, SRC, and DST must be of the extended 



R)"^, where C, R, and N are of type extended. 



Example 




C <— (1 + 


R)N, WP 


PEA 
PEA 
PEA 


R flOR 
N flOR 
C ADR 



; push adUress of R 

; push address of N 

; push address of C 

FCQMPQLN) ; conpound 
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Appendix A 
68000 SANE Access 



In your assemblies include the file TLASM/SANEMACS.TEXT, which contains 
the macros mentioned in this manual. The standard version is for Macintosh. 
For programs that will run on Lisa, redefine the symbol FPBYTRAP as 
follows: 

FPBYTRftP .EQU 

On Macintosh, the object code for FP68K and ELEMS68K is automatically 
loaded as needed by the Package Manager. On Lisa, it suffices to link your 
assembled code with the intrinsic unit file lOSFPLIB.OBJ. 
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AppendixB 
68000 SANE Macros 



FILE: SflrCMflCS.TEXT 

These macros and equates give assembly language access to 
the 68K floating-point arithmetic routines. 



; WARNING: set FPBYTRAP for your system. 



FPBYTRAP 


.EOU 
.MACRO JSRFP 


1 


for Lisa, 1 for Macintosh 






.IF FPBYTRAP 








FP68K 


/ 


defined in TOOLMACS 






.ELSE 










.REF 


FP68K 








JSR 


FP68K, 








.ENDC 










.ENDM 










.MACRO JSRELEMS 








.IF FPBYTRAP 








ELEMSedK 


defined in TOOLMACS 






.ELSE 










.REF 


ELEMS68K 








JSR 


ELEMS68K 








.ENDC 










.ENDM 








; Operat 


ion code masks. 








FOftDD 


.EOU 


$0000 , 


add 




FOSUB 


.EOU 


$0002 , 


subtract 




FOMUL 


.EOU 


$0004 , 


multiply 




FCDIV 


.EOU 


$0006 , 


divide 




FOOIP 


.Eai 


$0008 , 


compare, no exception from 


unordered 


FOCPX 


.EOU 


$000ft , 


compare, signal invalid if 


unordered 



B-1 



6800Ci S/^NE Engine 



68000 S^NE Macros 



FURtli 


.EQU 


$000C , 


remainder 


F0Z2X 


.EQU 


$000E , 


convert to extended 


F0X2Z 


.EOU 


$0010 , 


convert from extended 


FOSORT 


.EOU 


$0012 , 


square root 


FORTI 


.EOU 


$0014 , 


round to integral value 


FOTTI 


.EQU 


$0016 , 


truncate to integral value 


FOSCftLB 


.EOU 


$0018 , 


binary scale 


FOLOGB 


.EOU 


$001ft , 


binary log 


FOCLftSS 


.EOU 


$001C , 


classify 


; UNDEFIhED 


.EOU 


$00 IE 




FDSFTFNV 


.EOU 


$0001 , 


set environment 


FOGtItNV 


.EOU 


$0003 , 


get enviroiment 


FOSETHV 


.EOU 


$0005 , 


set halt vector 


FIK^IHV 


.EOU 


$0007 , 


get halt vector 


F0D2B 


.EOU 


$0009 , 


convert decimal to binary 


F0B2D 


.EOU 


$0008 , 


convert binary to decimal 


FONEG 


.EOU 


$000D , 


negate 


FOABS 


.EOU 


$000F , 


absolute 


FOCPYSGNX 


.EOU 


$0011 , 


copy sign 


FONEXT 


.EOU 


$0013 , 


next-after 


FOSETXCP 


.EOU 


$0015 , 


set exception 


FOPROCBfTRY 


.EOU 


$0017 , 


procedure entry 


FOPROCEXIT 


.EOU 


$0019 , 


procedure exit 


FOTESTXCP 


.EOU 


$001B . 


; test exception 


; UNDEFINED 


.EOU 


$00 ID 




; UNDEFINED 


.EOU 


$001F 





; Operand format masks. 



FFEXT 


.EOU 


$0000 , 


extended 


— 80-bit float 


FFDBL 


-EOU 


$0800 , 


double 


— 64-bit float 


FFSGL 


.EOU 


$1000 , 


single 


~ 32-bit float 


FFINT 


.EOU 


$2000 , 


integer 


— 16-bit integer 


FFLNG 


.EOU 


$2800 , 


long int 


— 32-bit integer 


FFCOMP 


.EOU 


$3000 , 


ccsnp 


— 64-bit integer 



Precision code masks: forces a floating point output 
value to be coerced to the range and precision specified. 



FCEXT 
FCDBL 
FCSGL 



.EOU $0000 ; extended 
.EOU $4000 ; double 
.EOU $8000 ; single 
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Operation macros: operand addresses should already be on 
the stack, with the destination address on top. The 
suffix X, D, S, C, I, or L determines the format of the 
source operand — extended, double, single, comp, 
integer, or long integer, respectively; the destination 
operand is always extended. 



Rddition. 



.MACRO 


FADDX 




MOVE.W 


#FFEXT+FOADD,- 


-(SP) 


JSRFP 






.ENDM 






.MACRO 


FADDD 




MOVE.W 


*FFDBL+FOADD, ■ 


-(SP) 


JSRFP 






.ENDM 






.MACRO 


FADDS 




MOVE.W 


JKFFSGL+FOADD,- 


-(SP) 


JSRFP 






.ENDM 






.MACRO 


FADDC 




MOVE.W 


^¥FFCOMP+FOADD, 


.-(SP) 


JSRFP 






.ENDM 






.MACRO 


FADDI 




MOVE.W 


*FFINT+FOADD,- 


-(SP) 


JSRFP 






.ENDM 






.MACRO 


FADDL 




MOVE.W 


#FFLNG+FOADD,- 


-(SP) 


JSRFP 






.ENDM 






; Subtraction. 






.MACRO 


FSUBX 
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liOVE.W *FFEXT+FOSUB,-(SP) 

JSRFP 

-ENDM 

.MACRO FSUBD 

MOVE.W #FFDBL+FOSUB,-(SP) 

JSRFP 

.ENDM 

.MACRO FSUBS 

MOVE.W #FFSGL+FOSUB.-(SP) 

JSRFP 

.ENDM 

.MACRO FSUBC 

MOVE.W #FFCOMP+FOSUB,-(SP) 

JSRFP 

.ENDM 

.MACRO FSUBI 

MOVE.W #FFINT+FOSUB,-(SP) 

JSRFP 

.ENDM 

-MACRO FSUBL 

MOVE.W #FFLNG+FOSUB,-(SP) 

JSRFP 

.ENDM 



; Multiplication. 

.MACRO FMULX 

MOVE.W #FFEXT+FONUU -(SP) 

JSRFP 

.ENDM 

.MACRO FMULD 

MOVE.W ^FFDBL+FOMUL, -(SP) 
JSRFP 
.ENDM 

.MACRO FMULS 

MOVE.W *FFSGL+FOMUL,-(SP) 

JSRFP 

.ENDM 

.MACRO FMULC 
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MOVE.W #FFCOMP+FOMUL,-(SP) 

JSRFP 

.ENDM 

.MACRO FMULI 

MOVE.W «FFINT+FOMUL^-(SP) 

JSRFP 

.ENDM 

.MACRO FMULL 

MOVE.W #FFLNG+FOMUU-(SP) 

JSRFP 

.ENDM 



Division. 



.MACRO FDIVX 

MOVE.W #FFEXT+FODIV,-(SP) 

JSRFP 

-ENDM 

.MACRO FDIVD 

MOVE.W #FFDBL+FODIV,-(SP) 

JSRFP 

.ENDM 

.MACRO FDIVS 

MOVE.W #FFSGL-«-FODIV,-(SP) 

JSRFP 

.ENDM 

.MACRO FDIVC 

MOVE.W *FFCOMP+FODIV,-(SP) 

JSRFP 

.ENDM 

.MACRO FDIVI 

MOVE.W #FFINT+FODIV,-(SP) 

JSRFP 

-ENDM 

.MACRO FDIVL 

MOVE.W *FFLNG+FOOIV,-(SP) 

JSRFP 

.ENDM 
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; Square root 



.MACRO FSQRTX 
MOVE.W *FOS0RT,-(SP) 
JSRFP 
.ENDM 



; Round to integer, according to the current rounding mode, 



.MACRO FRINTX 
MOVE.W *FORTI,-(SP) 
JSRFP 
.ENDM 



; Truncate to integer, using round toward zero. 



.MACRO FTINTX 
MOVE.W #FOTTI,-(SP) 
JSRFP 
.ENDM 



; Remainder. 



.MACRO FREMX 

MOVE.W #FFEXT+FOREM,-(SP) 

JSRFP 

.ENDM 

-MACRO FREMD 

MOVE.W *FFDBL+FOREM,-(SP) 

JSRFP 

.ENDM 

.MACRO FREMS 

MOVE.W #FFSGL+FOREM,-(SP) 

JSRFP 

.ENDM 

.MACRO FREMC 

MOVE.W *FFCOMP+FOREM,-(SP) 

JSRFP 

.ENDM 
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.MACRO FREMI 

MOVE.W #FFINT+FOREM,-(SP) 

JSRFP 

.ENDM 

.MACRO FREML 

MOVE.W *FFLNG+FOREM,-(SP) 

JSRFP 

.Er©M 



; Logb. 



.MACRO FLOGBX 
MOVE.W *FOLOGB,-(SP) 
JSRFP 
.ENDM 



; Scalb. 



.MACRO FSCALBX 

MOVE.W #FFINT+FOSCALB,-(SP) 

JSRFP 

.ENDM 



; Copy-sign. 



.MACRO FCPYSGNX 
MOVE.W *FOCPYSGN,-(SP) 
JSRFP 
.ENDM 



Negate. 



.MACRO FNEGX 
MOVE.W #FONEG,-(SP) 
JSRFP 
.ENDM 
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Absolute value. 



.MACRO FABSX 
MOVE-W #FOftBS,-(SP) 
JSRFP 
.ENDM 



; Next-after. ISOTE: both operands are of the sane 
; format, as specified by the usual suffix. 

.MACRO FNEXTS 

MOVE.W #FFSGL+FONEXT,-(SP) 

JSRFP 

-ENDM 

.MACRO FhEXTD 

MOVE.W #FFDBL+FONE>Cr,-(SP) 

JSRFP 

.ENDM 

.MACRO FNEXTX 

MOVE.W #FFEXT+FONEXT,-(SP) 

JSRFP 

.ENDM 



Conversion to extended. 

.MACRO FX2X 

MOVE.W #FFEXT+F0Z2X,-(SP) 

JSRFP 

.ENDM 

.MACRO FD2X 

MOVE.W *FFDBL+F022X,-(SP) 

JSRFP 

.ENDM 

.MACRO FS2X 

MOVE.W *FFSGL+F0Z2X,-(SP) 

JSRFP 

.ENDM 
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.MACRO FI2X 

MOVE.W #FFINT+F0Z2X,-(SP) 

JSRFP 

.ENDM 

.MACRO FL2X 

MOVE.W *FFLNG+F0Z2X,-(SP) 

JSRFP 

.ENDM 

.MACRO FC2X 

MOVE.W *FFC0MP+F022X,-(SP) 

JSRFP 

.ENDM 



Conversion from extended. 

.MACRO FX2D 

MOVE.W *FFDBL+F0X2Z,-(SP) 

JSRFP 

.ENDM 

.MACRO FX2S 

MOVE.W #FFSGL+F0X22,-(SP) 

JSRFP 

.ENDM 

.MACRO FX2I 

MOVE.W #FFINT+F0X2Z,-(SP) 

JSRFP 

.ENDM 

.MACRO FX2L 

MOVE.W #FFLNG+F0X2Z,-(SP) 

JSRFP 

.ENDM 

.MACRO FX2C 

MOVE.W #FFC0MP+F0X22,-(SP) 

JSRFP 

.ENDM 
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; Binary to decimal conversion. 



.MACRO FX2DEC 

mVE.W #FFEXT+FCB2D, -(SP) 

JSRFP 

.ENDM 

.MACRO FD2DEC 

MOVE.W #FF[)BL+F0B2D, -(SP) 

JSRFP 

.ENDM 

.MACRO FS2DEC 

MOVE.W #FFSGL+F0B2D,-(SP) 

JSRFP 

.ENDM 

.MACRO FC2DEC 

MOVE.W #FFC0MP+F0B2D,-(SP) 

JSRFP 

.ENDM 

.MACRO FI2DEC 

MOVE.W #FFINT+F0B2D,-(SP) 

JSRFP 

.ENDM 

.MACRO FL2DEC 

MOVE.W #FFLNG+F0B2D, ~(SP) 

JSRFP 

.ENDM 



; Decimal to binary conversion. 



-MACRO FDEC2X 

MOVE.W *FFEXT+F0D2B, -(SP) 

JSRFP 

.ENDM 

.MACRO FDEC2D 

MOVE.W #FFDBL+F0D2B,-(SP) 

JSRFP 

.ENDM 
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.Mf€RO FDEC2S 

MOVE.W #FFSGL+F0D2B,-(SP) 

JSRFP 

.ENDM 

.MACRO FDEC2C 

I1C3VE.W #FFC0MP+FCD2B,-(SP) 

JSRFP 

.ENDM 

.MACRO FDEC2I 

MOVE.W *FFINT+F0D2B,-(SP) 

JSRFP 

.ENDM 

.MACRO FDEC2L 

MOVE.W «FFLNG+F0D2B,-(SP) 

JSRFP 

.ENDM 



; Compare, not signaling invalid on unordered. 

.MACRO FCMPX 

MOVE.W #FFEXT+FOCMP,-(SP) 

JSRFP 

.ENDM 

.MACRO FCMPD 

MOVE.W #FFDBL+FOCMP,-(SP) 
JSRFP 
.ENDM 

.MACRO FCMPS 

MOVE.W #FFSGL+FOCMP,-(SP) 

JSRFP 

.ENDM 

.MACRO FCMPC 

MOVE.W #FFCOMP+FOCMP,-(SP) 
JSRFP 
.ENDM 

.MACRO FCMPI 

MOVE.W *FFINT+FOCMP,-(SP) 

JSRFP 

.ENDM 
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.MACRO FCMPL 

MOVE.W #FFLNG+FOCMP,-(SP) 

JSRFP 

.ENDM 



; Compare^ signaling invalid on unordered. 

.MACRO FCPXX 

MOVE.W #FFEXT+FOCPX,-(SP) 

JSRFP 

.ENDM 

.MACRO FCPXD 

MOVE.W #FFDBL+FOCPX,-(SP) 
JSRFP 
.ENDM 

.MACRO FCPXS 

MOVE.W #FFSGL+FOCPX,-(SP) 

JSRFP 

.ENDM 

.MACRO FCPXC 

MOVE.W #FFCOMP+FOCPX,-(SP) 

JSRFP 

.ENDM 

.MACRO FCPXI 

MOVE.W #FFINT+FOCPX, -(SP) 

JSRFP 

.ENDM 

.MACRO FCPXL 

MOVE.W #FFLNG+FOCPX, -(SP) 

JSRFP 

.ENDM 



; The follwing macros define a set of so-called floating 
; branches. They presume that the appropriate compare 
; operation^ macro FCffz or FCPXz, precedes. 

.MACRO FBEQ 
BEO %1 
.ENDM 
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.MACRO FBLT 

BCS %1 
.ENDM 

.MACRO FBLE 

BLS %1 
.ENDM 

.MACRO FBGT 

BGT %1 
.ENDM 

•MACRO FBGE 

BGE %1 
.ENDM 

.MACRO fBULT 

BLT %1 
-ENDM 

.MACRO FBULE 

BLE %1 
.ENDM 

.MACRO FBUGT 

BHI %1 
.ENDM 

.MACRO FBUGE 

BCC %1 
.ENDM 

.MACRO FBU 

BVS %1 
.ENDM 

.MACRO FBO 

BVC %1 
.ENDM 

.MACRO FBNE 

BNE %1 
.ENDM 
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.MACRO FBLE 

BEQ %1 

BVS %1 
.EM)M 

.MACRO FBLG 

BTC %1 

BVC %1 
.EMDM 



Short branch versions. 



.MACRO 

BEO.S 

.0©M 


FBEOS 
%1 


.MACRO 

BCS.S 

.Q€M 


FBLTS 
%1 


.MACRO 
BLS.S 
.QCM 


FBLES 
%1 


.MACRO 

BGT.S 

.ENDM 


FBGTS 
%1 


.MACRO 

RGF.S 

.ENDM 


FBGES 
%1 


.MACRO 

BLT.S 

.ENDM 


FBULTS 
%1 


.MACRO 

BLE.S 

.ENDM 


FBULES 
%1 


.MACRO 

BHI.S 

.ENDM 


FBUGTS 
%1 
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.MACRO 


FBUGES 






BCC.S 


%1 






.ETOM 








.MACRO 


FBUS 






BVS.S 


%1 






.ENDM 








.MACRO 


FBOS 






BVC.S 


%1 






.ENDM 








.MACRO 


FBNES 






BNE.S 


%1 






.ENDM 








•MACRO 


FBUES 






BEO.S 


%1 






BVS.S 


%1 






.ENDM 








.MACRO 


FBLGS 






BNE.S 


%1 






BVC.S 


%1 






.ENDM 








; Class and sign inquiries. 






FCSNAN 


.EOU 1 


; signaling NfflS 




FCONAN 


.EOU 2 


; quiet NAN 




FCINF 


.EOU 3 


; infinity 




FCZERO 


.EOU 4 


; zero 




FCNORM 


.EOU 5 


; normal number 




FCDENUWi 


.EOU 6 


; denorraal number 




.MACRO 


FCLASSS 






MOVE.W 


#FFSGL+FOCLASS, 


-(SP) 




JSRFP 








.ENDM 








.MACRO 


FCLASSD 






MOVE.W 


«FFDBL+FOCLASS, 


-(SP) 




JSRFP 








.ENDM 
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.MACRO 
MOVE.W 
JSRFP 
.ENDM 



FCLftSSX 
*FFEXT+FOCLftSS,-(SP) 



Bit indexes for bytes of floating point environment word. 



invalid operation 

underflow 

overflew 

division by zero 

inexact 

low bit of rounding mode 

high bit of rounding mode 

last round result bit 

double precision control 

single precision control 



FBINVALID 


.EQU 


; 


FBUFLOW 


.EOU 


1 


FBOFLOW 


.EOU 


2 ; 


FBDIV2ER 


.EOU 


3 ; 


FBINEXACT 


.EQU 


4 ; 


FBRhDLO 


.EQU 


5 ; 


FBRNDHI 


.EOU 


6 ; 


FBLSTRhD 


.EOU 


7 ; 


FBDBL 


.EOU 


5 ; 


FBSGL 


.EQU 


6 



Get and set environment. 



.MACRO FGETENV 
MOVE.W *FOGETENV,-(SP) 
JSRFP 
.ENDM 



.MACRO 
MOVE.W 
JSRFP 
.ENDM 



FSETENV 
«FOSETENV,-(SP) 



; Test and set exception. 



.MACRO FTESTXCP 
MOVE.W #FOTESTXCP,-(SP) 
JSRFP 
.ENDM 

.MACRO FSETXCP 
MOVE.W #FOSETXCP,-(SP) 
JSRFP 
.ENDM 
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; Procedure entry and exit. 

.MACRO FPROCENTRY 
MOVE.W #FOPROCEhfrRY,-(SP) 
JSRFP 
.ENDM 

.MACRO FPROCEXIT 
MOVE.W #FOPROCEXIT, -(SP) 
JSRFP 
.ENDM 



Get and set halt vector. 



.MACRO FGETHV 
MOVE.W #FOGETHV,-(SP) 
JSRFP 
.ENDM 

.MACRO FSETHV 
MOVE.W #FOSETHV,-(SP) 
JSRFP 
.ENDM 



Elementary function operation code masks. 



FOLNX 
F0L0G2X 
FOLNIX 
F0L0G21X 


.Egu 

.EOU 
.EOU 
.EOU 


$0000 , 
$0002 , 
$0004 , 
$0006 , 


base-e log 
base-2 log 
In (1 + x) 
log2 (1 + x) 


FOEXPX 
F0EXP2X 
FOEXPIX 
F0EXP21X 


.EQU 

.Egu 
.Egu 
.Egu 


$0008 , 
$000ft , 
$000C , 
$000E , 


base-e exponential 
base-2 exponential 
exp (x) - 1 
exp2 (x) - 1 


FOXPWRI 
FOXPWRY 
FOCOMPOUNDX 
FOANNUITYX 


.Egu 
.Egu 
.Egu 

.EOU 


$8010 , 
$8012 , 
$C014 , 
$C016 , 


integer exponentiation 
■ general exponentiation 
, compound 

annuity 


FOSINX 
FOCOSX 


-Egu 
.Egu 


$0018 , 
$001A , 


sine 
, cosine 
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FOTANX .EQU $001C ; tangent 

FOftTANX .EQU $001E ; arctangent 

FORANDOMX .EOU $0020 ; random 



; Elwnentary function macros. 

.MACRO FLNX 
MOVE.W *FOLKK,-(SP) 
JSRELEMS 
.ENDM 



base-e log 



.MACRO FL0G2X 
MOVE.W «F0L0G2X, -(SP) 
JSRELEMS 
.ENDM 

.MACRO FLNIX 
MOVE.W #F0LN1X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FL0G21X 
MOVE.W *F0L0G21X,-(SP) 
JSRELEMS 
.ENDM 



base-2 log 



In (1 + x) 



log2 (1 + x) 



.MACRO FEXPX 
MOVE.W #FOEXPX,-(SP) 
JSRELEMS 
.ENDM 



base-e exponential 



.MACRO FEXP2X 
MOVE.W *F0EXP2X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FEXPIX 
MOVE.W *F0EXP1X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FEXP21X 
MOVE.W *F0EXP21X,-(SP) 
JSRELEMS 
.ENDM 



base-2 exponential 



exp (x) - 1 



exp2 (x) - 1 



B-18 



6SlX?0 S/^NE Engine 



63000 Sf^iNE Macros 



.MACRO FXPWRI 
MOVE.W #F0XPWRI,-(a3) 
JSRELEMS 
.ENDM 

.MACRO FXPWRY 
MOVE.W #FOXPWRY,-(SP) 
JSRELEMS 
.ENDM 



Integer exponential 



general exponential 



.MACRO FCOMPOUNDX ; compound 
MOVE.W #FOCOMPOUNDX,-(SP) 
JSRELEMS 
.ENDM 



.MACRO FANNUITYX ; 
MOVE.W *FOANNUITYX,-(SP) 
JSRELEMS 
.ENDM 



annuity 



.MACRO FSINX 
MOVE.W #FOSINX,-(SP) 
JSRELEMS 
.ENDM 



sine 



.MACRO FCOSX 
MOVE.W #FOCOSX,-(SP) 
JSRELEMS 
.ENDM 



cosine 



.MACRO FTANX 
MOVE.W #FOTANX,-(SP) 
JSRELEMS 
.ENDM 



tangent 



.MACRO FATANX 
MOVE.W #FOATANX,-(SP) 
JSRELEMS 
.ENDM 



arctangent 



.MACRO FRANDOMX ; 
MOVE.W «FORANDOMX,-(SP) 
JSRELEMS 
.ENDM 



random nunber generator 
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; NfiN codes. 




NANSQRT .EOU 


1 ; 


NANADD .EOU 


2 ; 


NANDIV .EOU 


4 ; 


NANMUL .EOU 


8 ; 


NANREM .EOU 


9 ; 


NANftSCBIN .EOU 


17 ; 


NANCOMP .EOU 


20 ; 


NAN2ER0 .EOU 


21 ; 


NANTRIG .EOU 


33 ; 


NANINVTRIG .EOU 34 ; 


NANLOG .EOU 


36 ; 


MANPOWER .EOU 


37 ; 


NANFINAN .EOU 


38 ; 


NANINIT .EOU 


255 ; 



Invalid squeore root such as sqrt(-l). 
Invalid addition such as +INF - +INF. 
Invalid division such as 0/0. 
Invalid multiply such as * INF. 
Invalid remainder or mod such as x F£M 0. 
Attempt to convert invalid ASCII string. 
Result of converting comp NaN to floating. 
Attempt to create a N^ with a zero code. 
Invalid argument to trig routine. 
Invalid argLmient to inverse trig routine. 
Invalid argiment to log routine. 
Invalid argiment to x^i or x'^y routine. 
Irwalid argtment to financial function. 
Uninitialized storage. 
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This Guide contains diagrams of the SANE data formats and the 68K SANE 
operations and environment word. 

C.1 Data Foormats 

Each of the diagrams below is followed by the rules for evaluating the number 

V. 

In each field of each diagram, the leftmost bit is the msb and the rightmost is 
the Isb. 



Fonrat DiflQTflR Synritols 



V value of number 

s sign bit 

e biased exponent 

i explicit one' s-bit (extended type only) 

f fraction 




Single: 32 Bits 




1 8 23 


widths 


|s| e 1 f 


~i 



if < e < 255, then v = (-l)s * 2(e-127) * (l.f); 

if e = and f =!*■/ 0, then v = (-l)s * 2(-126) * (O.f); 

if e = and f = 0, then v = (-l)s ♦ 0; 

if e = 255 and f = 0, then v = (-l)s * oo; 

if e = 255 and f =K-/ 0, then v is a NaN. 
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Double: 64 Bits 

1 11 



52 



widths 



if < e < 2047, then v = (-l)s * 2(e-1023) * (l.f); 
if e = and f ^/ 0, then v = (-l)s * 2(-1022) * (O.f); 
if e = and f = 0, then v = (-l)s * 0; 
if e = 2047 and f = 0, then v = (-l)s * oo; 
if e = 2047 and f =W 0, then v is a NsN. 



CfXiip: 64 Bits 

1 63 

isl d 



widths 



if s = 1 and d = 0, then v is the unique comp NoN; 
otherwise, v is the two's-complauent value of the 
64-bit representation. 



Extended: 80 Bits 

1 15 1 
Isl e jil 



63 
f 



widths 



if <= e < 32767, then v = (-1)5 * 2(e-16383) * (i.f); 
if e = 32767 and f = 0, then v = (-l)s * oo, regardless of i; 
if e = 32767 and f =!»■/ 0, then v is a NaN, regardless of i. 
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C2 Operafcions 

In the operations below^ the operation's mnemonic is followed lay the opword in 
parentheses: the first byte is the operation code; the second is the operand 
format code. For some operations^ the first byte of the opword (xx) is ignored. 

C2.1 Abtreviafcions and Symtmls 

The symbols and abbreviations in this section closely parallel those in the text, 
although some are shortened. In some cases, the same symbol has various 
meanings, depending on context. 



DST destination operand (passed by address) 

SRC source operand (passed by address), pushed before [^T 

SRC2 second source operand (passed by address), pushed before SRC 

Deia Types 

X extended (80 bits) 

D double (64 bits) 

S single (32 bits) 

1 Integer (16 bits) 
L longint (32 bits) 
C comp (64 bits) 
Dec decimal Record 
Decf orm decform Record 

68000 Processor Registers 

DO data register 

X extend bit of processor status register 

N negative bit of processor status register 

2 zero bit of processor status register 

V overflow bit of processor status register 

C carry bit of processor status register 

Exceptions 

I invalid operation 

U underflow 

overflow 

D divl de-by-zero 

X inexact 

For each operation, an exception marked with x indicates that the operation will 
signal the exception for some input. 
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Em.iironment and Halts 



EnWrd SfthE environment word (16-bit integer) 
HltVctr SANE halt vector (32-bit longint) 



C.2.2 Arithmetic C^»erd;icNns and Auxiliaen/ RoiAuks (Entzy PoirA RP68K) 

Operation Operands and Data Types Exceptions 

I U D X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 



I U D X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 

X - X - X 



I U D X 

X X X - X 

X X X - X 

X X X - X 

X - X - X 

X - X - X 

X - X - X 



I U D X 

X X X X X 

X X X X X 

X X X X X 

X X - X X 

X X - X X 

X X - X X 



ADD 


DST <- 


- DST 


+ SRC 


FfDDX (0000) 


X 


X 


X 


FADDD (0800) 


X 


X 


D 


FADDS (1000) 


X 


X 


S 


FftDDC (3000) 


X 


X 


C 


FftDDI (2000) 


X 


X 


I 


FADDL (2800) 


X 


X 


L 


SIIBTRflCT 


DST <- 


- DST 


- SRC 


FSUBX (0002) 


X 


X 


X 


FSUBD (0802) 


X 


X 


D 


FSUBS (1002) 


X 


X 


S 


FSUBC (3002) 


X 


X 


C 


FSUBI (2002) 


X 


X 


I 


FSUBL (2802) 


X 


X 


L 


MULTIPLY 


DST <- 


- DST 


* SRC 


FMULX (0004) 


X 


X 


X 


FMULD (0804) 


X 


X 


D 


FMULS (1004) 


X 


X 


S 


FMULC (3004) 


X 


X 


C 


FMULI (2004) 


X 


X 


I 


FMULL (2804) 


X 


X 


L 


DIVIDE 


DST <■ 


- DST / SRC 


FDIVX (0006) 


X 


X 


X 


FDIVD (0806) 


X 


X 


D 


FDIVS (1006) 


X 


X 


S 


FDIVC (3006) 


X 


X 


C 


FDIVI (2006) 


X 


X 


I 


FDIVL (2806) 


X 


X 


L 
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SQUARE ROOT DST 

FSORTX (0012) X 



<— 



scirt(DST) 
X 



I U D X 
X X 



Rdlf) TO INT DST 

FRINTX (0014) X 



<— 



rnd(DST) 
X 



I U D X 
X X 



TWJNC TO INT DST <— chop(DST) 
FTINTX (0016) X X 



I U D X 
X X 



REI1AIIf]ER DST <— DST REM SRC I U D X 

FREMX (OOOC) X X X x 

FREMD (080C) X X D x 

FREMS (lOOC) X X S x 

FREMC (300C) X X C X 

FREMI (200C) X X I x 

FREIiL (280C) X X L x 

DO <— integer quotient DST/SRC, 

between -127 and +127 



im BINARY 

FLOGBX (001ft) 


DST 
X 


<— 


logb(DST) 
X 


SCALE BINf«Y 

FSCALBX (0018) 


DST 
X 


<— 


DST * 2"SRC 
X I 


M-lifliTE 

FhEGX (OOOD) 


DST 
X 


<— 


-DST 
X 


ABSOLUTE VALUE 

FABSX (OOOF) 


DST 
X 


<— 


IDSTI 
X 



I U D X 

X — x - 

I U D X 

X X X - X 

I U D X 



I U D X 



COPY-SIGN SRC <- 
FCPYSGNX (0011) XDorS 



SRC with DST's sign 
XDorS XDorS 



I U D X 



NEXT-AFTER SRC 

FISEXTX (0013) X 

FNEXTD (0813) D 

Fr€XTS (1013) S 



<~ next after SRC toward DST I U D X 

X X X X X - X 

D D X X X - X 

S S X X X - X 
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C23 Conversions (Entxy Point FP68K} 

Operation Operands and Data Types 

CGWERT 



Exceptions 



Bin to Bin 

FX2X (0010 

FX2D (0810 

FX2S (1010 

FX2C (3010 

FX2I (2010 

FX2L (2810 

FD2X (080E 

FS2X (lOOE 

FC2X (300E 

FI2X (200E 

FL2X (280E 



DST 
X 
D 
S 
C 
I 
L 

X 
X 
X 
X 
X 



SRC 
X 
X 
X 
X 
X 
X 

D 
S 
C 
I 
L 



U D X 



- X 

- X 

- X 

- X 

- X 






Bin to Dec DST <~ SRC according to SRC2 

FX2DEC (OOOB) Dec X Decform 

FD2DEC (080B) Dec D Decform 

FS2DEC (lOOB) Dec S Decform 

FC2DEC (300B) Dec C Decform 

FI2DEC (200B) Dec I Decform 

FL2DEC (280B) Dec L Decform 

(First SRC2 is pushed^ then SRC, then DST.) 



I U D X 

X 
X 
X 
X 
X 
X 



X — 
X 

X — 



Dec to Bin 


DST <• 


- SRC 


FDEC2X (0009) 


X 


Dec 


FDEC2D (0809) 


D 


Dec 


FDEC2S (1009) 


S 


Dec 


FDEC2C (3009) 


C 


Dec 


FDEC2I (2009) 


I 


Dec 


FDEC2L (2809) 


L 


Dec 



I U D X 



X - 
X - 
X - 
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C.2.4 Compere and Classify (Entry Point FP68I^ 



Operation 


Ooerands and Data Tvpes 




Exceptions 


mnPARE 




No invalid 


Status 


Bits <— 


<relatlon> 




I U D X 


for unorctered 




where DST 


<relation> 


SRC 




FCMPX (0008) 




X 




X 


X 


FCMPD (0808) 




X 




D 


X 


FCMPS (1008) 




X 




S 


X 


FOiPC (3008) 




X 




C 


X 


FCMPI (2008) 




X 




I 


X 


FCMPL (2808) 




X 




L 


X 



(Invalid only for signaling NaN Inputs) 



Signal invalid 


Status Bits <— 


<relatlon> 




I 


if unordered 




where DST 


<relatlon> SRC 




FCPXX (000ft) 
FCPXD (080ft) 
FCPXS (100ft) 
FCPXC (300ft) 
FCPXI (200ft) 
FCPXL (280ft) 




X 
X 
X 
X 
X 
X 




X 
D 
S 
C 
I 
L 


X 
X 
X 
X 
X 
X 


<relation> 




Status Bits 
X N Z V C 








DST > SRC 













DST < SRC 




110 1 








DST = SRC 




10 








DST & SRC unordered 


10 









U D X 



CLflSSIFY <class> <— class of SRC 

<sign> < — sign of SFC 

DST <— (-l)^<sign> * <class> 



FCLASSX (OOIC) I 
FCLftSSD (081C) I 
FCLftSSS (lOlC) I 



I U D X 
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SRC 



<class> 



SRC 



<sian> 



signaling N^ 

quiet NaN 

infinite 

zero 

normalized 

denormallzed 



positive 

negative 1 



C.2.5 Environmenta] Control (ErAiy Point FP68K) 

Operation Ooerancte and Data Types 

GET EWIRDItENT DST <-- EnvWrd 

FGETENV (0003) I 



Exceptions 
I U D X 



SET ENVIROmENT 

FSETENV (0001) 



EnvWrd <-- SRC 
I 



(exceptions set by set-envirorment cannot cause halts) 



I U D X 

X X X X X 



TEST E)fl:GPTICN 

FTESTXCP (OOIB) 



Zbit < — SRC Xcps clear 
I 



I U D X 



SET EXCEPTION 

FSETXCP (0015) 



EnvWrd <— EnvWrd fthD SRC I U D X 

I X X X X X 



PnXEDURE ENIRr 

FPROCENTRY (0017) 



DST <~ EnvWrd^ EnvWrd <— I U D X 

I X X X X X 



PRDCEDUHE EXIT 

FPROCEXIT (0019) 



EnvWrd <— SRC AND current Xcps I U D X 

I X X X X X 
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CJL6 Halt Control (Enby Point FP68K} 



SET HALT VECTOR 

FSE7HV (xx05) 


HltVctr 


<~ SRC 
L 


I U D X 


GET HALT VECTOR 

FGETHV (0007) 


DST <— 

L 


HltVctr 


I U D X 



C^7 ElemerAary Functions (Entiy Point ELEMS68K) 



Ooeration 


Operands anc| Dat^ Types 

DST <— In(DST) 
X X 


f> 


cceotions 


BASE-E LOGflRTTHI 

FLNX (0000) 


I 
x 


U D X 

XX 


BASF-2 LOGflRIlHI 

FL0G2X (0002) 


DST 
X 


<— 


log2(DST) 
X 


I 

X 


U D X 

XX 


Bfl5E-E LOGl (mi) 

FLNIX (0004) 


DST 
X 


<— 


ln(l+DST) 
X 


I 

X 


U D X 

X - X X 


Bfl6E-2 iVRl 

FL0G21X (0006) 


DST 
X 


<— 


log2(l+DST) 
X 


I 

X 


U D X 

X - X X 


BflSF-E E^O^OCNnAL 

FEXPX (0008) 


DST 
X 


< — 


e'DST 
X 


I 

X 


U D X 

X X - X 


BffiF-2 EXMUCNTIAL 

FEXP2X (000ft) 


DST 
X 


< — 


2"DST 
X 


I 

X 


U D X 

X X - X 


BflGE-£E?a>l 

FEXPIX (OOOC) 


DST 
X 


< — 


e^DST - 1 
X 


I 

X 


U D X 

X X - X 


BflRF-2E)ff>l 

FEXP21X (OOOE) 


DST 
X 


< — 


2''DST - 1 
X 


I 

X 


U D X 

X X - X 
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INTEGER E3TCNENnftTIfW DST <— DSrSRC 
F?<R«IRI (8010) X X I 



I U D X 

X X X X X 



GEICRfflL E)«l€NnftTION DST <— DST^SRC 
FXPWRY (8012) X XX 



I U D X 

X X X X X 



COffOfO INTEREST 

FCOMPOUND (COW) 



DST <— corapound(SRC2^SRC) 
X XX 



(SRC2 is the rate; SRC is the number of periods.) 



ffffJITY FflODR 

FANNUITY (C016) 



DST <~ annul ty(SRC2, SRC) 
X XX 



(sra;2 is the rate; SRC is the number of periods.) 



I U D X 

X X X X X 



I U D X 

X X X X X 



SINE 

FSINX (0018) 



CCBINE 

FCOSX (OOIA) 



TANGENT 

FTftNX (OOIC) 



flRCTflNGENT 

FATANX (OOIE) 



RflNDGM 

FRANDX (0020) 



DST 
X 




sin(DST) 
X 


DST 
X 


<— 


cos (DST) 
X 


DST 
X 


<— 


tan(DST) 
X 


DST 
X 


<— - 


atan(DST) 
X 


DST 
X 


<~ 


randoro(DST) 
X 



I U D X 

XX X 



I U D X 

XX — X 



I U D X 

X X - X X 

I U D X 

XX X 



I U D X 

X X X - X 
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C3 Envirimmenl; Word 

The floating-point environment is encoded in the 16-bit integer format as shown 
below in hexadecimal: 

nisb Isb 

I -TrTrTxTd" iT iTj'i I ^'p'TrTxTdiT m iT" 



rounding exception rounding halt 
direction flags precision enables 

rounding direction^ bits 6000 rr 
00(X) — to-nearest 
2000 ~ upward 
4000 ~ downward 
6000 — toward-zero 

exception flags^ bits IFOO 

0100 ~ invalid i 

0200 ~ underflow u 

0400 ~ overflow o 

0800 — division-by-zero d 

1000 — inexact x 

rounding precision^ bits 0060 WR 

0000 ~ extended 
0020 — double 
0040 — single 
0060 — UNDEFirCD 

halt enabled, bits 00 IF 

0001 ~ invalid I 

0002 ~ underflow U 
0004 ~ overflow 
0CK)8 — division-by-zero D 
0010 ~ inexact X 

Bits 8000 and 0080 are undefined. 

Note that the default environment is represented by the integer value zero. 
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The StdUhit Unit 



1 Inbrodtiction 

StdUnit is the "Standard Unit," an intrinsic unit that presides a number of 
standard functions. It contains functions dealing with: 

■ Character and string manipulartion. 

■ File name manipulation. 

■ Prompting. 

" Error messages. 

■ Special Workshop features. 
• Conversions. 

Workshop tools should use the unit wherev^ possible, especially for 
prompting and Operating System error reporting, to make the Workshop 
interface consistent. 

Note: All names in StdUnit begin with the letters SU. This avoids name 
conflicts when incorporating the unit into your code and identifies where 
things come from. 

2 Functional Areas 

2.1 Initialization 

StdUnit needs to be initialized before it can be used. Using the unit without 
initializing it will often result in an address or bus error. 

2J2 String and Character Manipulation 

StdUnit provides a standard string type, SUStr; a type for sets of characters; 
definitions for several standard characters (such as CR and BS); and 
procedures for case conversion, trimming blanks, and appending strings and 
characters. 

23 File Name Manipulation 

File name functions let you determine if a pathname is a volume or device 
name only; add extensions (such as .TEXT) to the file names (the procedure 
knows the conventions about when extensions should and should not be 
added); splitting a pathname into its three basic components — the device, 
volume, or catalog component, the file name component, and the extension 
component; putting the components back together into a file name; and 
modifying a file name given optional defaults for missing volume, file rar 
extension components. 

Note: Several of the procedures return overflow flags for identifying when a 
file name component has exceeded its character limit. You may choose to 
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ignore the overflow condition, particularly if you think it likely to occur only 
in perverse circumstances. 

Note: The string parameters to these procedures are typed differently, 
sometimes SUStr's, or VAR SUStr's, or SUStrP's (pointers to SUStr's). This is 
to avoid problems with Pascal string typing when using the procedures with 
strings that are not SUStr's (e.g., PathName's), and to take into account the 
cases in which the parameters are likely to be string constants. 

2.4 Prorrviting 

StdUnit provides a number of procedures to get characters, strings, file 
names, integers, yes/no responses, etc., from the console, providing for 
default values where appropriate. 

Most of the prompting procedures return a PrompState indicating whether an 
escape [CLEAR] was typed, whether the default was taken, or whether there 
was a request for options with ?. The states returned are given for each 
procedure. You can ignore the prompt states you are not interested in. For 
example, if you don't want to treat ? as an option request, you can ignore 
the SUOptions state and not treat the ? returned as a special character. 

23 Error Text Retrieval 

StdUnit provides a mechanism to retrieve single-line error messages from 
specially formatted error files. Error messages can be looked up by number 
in one or more error files. 

You can use the OS error file OSErrs.ERR to return a real message when an 
OS error occurs (see Example 2, below). Note that OS errors are also 
returned via Pascal's lORESULT. 

The ErrTool program lets you make your own compacted message files. 
Using this error mechanism, you can add and modify messages without 
recompiling your program. ErrTool is described in the Workshop User's 
Guide, Chapter 11, The Utilities. 

A call to retrieve a message opens the error file, searches the directory for 
the error number, finds location of the message, and returns the text. 

A program can use StdUnit to access more thaai one error file 
simultaneously. For example, your program can access different files for OS 
error messages and your own messages. 

Z6 Workshop Support 

Special Workshop f unctior^ let you: 

■ Stop the execution of an EXEC file in progress. 

■ Find out the name of the boot and current prefix volumes (SysVols). 

■ Use a super-RESET that will try to open a file first on the prefix 
volume, then on the boot volume, then on the current process volume. 
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2.7 ConMorsions 

Conversion procedures let you convert from integers and longints to strings, 
and from strings to integers and longints. 

3 Examples 

Exemple 1 

Assume we are going to prompt for an output file name (OutFName) and that 
we already have the input file name (InFName). We will use SUSplitFN to 
split the input file name into its various components. Then we will prompt 
for the output file name (with SUGetFN) using the volume and file name 
components of the input file name as defaults but with a .ERR extension. 
We then do a CASE on the prompt state (PState) returned by SUGetFN. The 
will terminate if the file specification is an escape [CLEAR]; say that no 
option are available if ? is typed as an option request; prompt again if no 
file is specified, since we want to require an output file; and fall through if 
the default is accepted or some other file is specified. Note that we only 
have to check for the prompt states we are interested in for special 
handling. 

9999: 

URITE ('Nane of Ezror Output File '); 
SUSplitFN (einFNane, gVolN, iFN, fExt); 
SUGetFN (eOutFNme, PState, VolN, FN, '.ERR'); 
CASE PState OF 
SUEscape.- EKIT (EirFileP); {exit fron progran} 
SUDptions: BEGIN 

HRITELN ('No options are available. '); 
GOTO 9999; 

Bi); 

SLflone: GOTO 9999; 
END; {CASE} 
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Example 2 

Suppose we have just made a Pascal I/O call and want to report an error 
(along with the OS message text) if we receive a nonzero lORESULT. Note 
that we copy lORESULT into our lOStatus variable so that the subsequent 
WRITELN will not reset the value of lORESUlLT before we get a chance to 
use it. (EMsg should be a SUStr.) 

IF lORESULT <> THEN 
BEGIN 

lOStatus := lORESULT; 
HRITELN ('EJnrtnr opening input file.'); 
SUErrText ('OsErrs.ERR', lOStatus^ IDIsg); 
HRITELN (EHsg); 

Of); 
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A Interface 



- SUrStdUnit 



Copyright 1983, 1984, Apple Computer, Inc. 






This unit provides a number of standard type definitions and a collection 
of procedures which perform a variety of common functions. The areas 
covered are: 

(1) String and Character manipulation 

(2) File Neme Manipulation 

(3) Prompting 

(4) Retrieval of messages from disk 

(5) Development System Support 

(6) Conversions 

Fred Forsman 4-25-84 



{$SETC ForOSllorHigher := TRUE} 

{$R-} { make it fast, no range checking } 
{$S SULib } 

UNIT StdUnit; 
INTRINSIC; 

INTERFACE 



USES 

{$U libOS/SysCall.obj } SysCall, { for definition of PathNaroe, etc. 

{$U libPL/IPasLibCall.obj } PasLibCall, 

{$U libPL/PPasLibC.obj } PPasLibC; 



CONST 
SUMaxStrLeng 
SUNullStr 
SUSpace 
SUOrdCR 
SUMaxPNLeng 
SUMaxVNLeng 
SUhaxFNLeng 
SUVolSuffix 

TYPE 
SUSetOfChar 
SUStrP 



255; 



13; 
66; 
33; 
32; 



{ max length of path neme } 

{ max length of volume neme, includes leading 

{ maximum length of file name } 

{ suffix or end of device or volume neme } 



SET OF CHAR; 
^SUStr; 
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SLBtrP = ''SUStX; 

SUStr = STRING [255]; 

SUVolName = STRING [SUMaxVNLeng]; 
SUFile = FILE; 

SUFileP = ''SUFile; 

PrcjrnptState = (SUDefault, 

SLEscape^ 

aHone, 

SLDptions, 

SUValid, 

SUInvalid 

); 
ErrTextRet = (SUOk, 

SUBacEFOpen, 
SUBadEFRead, 
SUErrNNotFound 

); 
ConvNState = (SUValidN, 
SUNoN, 
SUBadN, 
SlOverFlw 
); 



the default (if any) was chosen) } 

the "Clear" key was pressed } 

nothing specified in response to prcmpt } 

"?" was entered — ie, an option query } 

valid reponse } 

invalid reponse — eg^ non-ncjinber to SUGetInt} 



successful } 

could not open error file } 
error reading error file } 
error nimiber not found } 

valid number } 

no nimiber — nothing specified } 

iiwalid number } 

overflow — number too big } 



VAR 
SUOsBootV : SUVolName; { The volume the OS was booted from } 
SUMyProcV : SUVolNsme; { The volume liyProcess was started from } 
SUBell^ SUBackSpace^ SUCr, SUTab^ SUEsc, 

SUDle, SUNul : CHf¥?; { predefined ch vars } {ff 1/23/84} 
SUNullS : aBtr; { predefined str var } 
SLKeyBoard : INTERACTIVE; { non-echoing console^ used by SUGetCh } 

{ff 2/29/84} 



{============================== INIT AND DONE ==«========« 



issssssssxsssssaass 



PROCEDURE SUInit; 

{ Should be called before using rest of unit. On the OS this opens 
"-KeyBoard". It also initializes the standard character variables. } 

PROCEDURE SUDone; 

{ Can be called when done using unit (although this is not strictly 
necessary. On the OS this closes "-KeyBoard". } 

{============================= STRINGS AND CHARS =============================} 

FUNCTION SUUpCh (Ch : CHAR) : CHAR; 

{ SUUpCh returns the ch that was passed^ uppercased if it was lower 
case. } 
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FUNCTION SULowCh (Ch : CHAR) : CHAR; 
{ ^LcnCh returns the ch that was passed^ lowercased if It was upper 
case. } 

PROCEDURE SUUpStr (S: SUStrP); 

{ SUJpStr uppercases the string that is passed. } 

PROCEDURE SULowStr (S: SUStrP); 

{ SULowStr lowercases the string that Is passed. } 

FUNCTION SUEqStr (SI: SUStrP; S2: SUStrP) : BOOLEAN; {ff 2/29/84} 
{ SLEcjStr returns IWE if the two strings are equal (ignoring case) . } 

FUNCTION SUEq2Str (SI: SUStrP; S2: SUStr) : BOOLEAN; {ff 3/7/84} 
{ SUEq2Str returns TRUE if the two strings are equal (ignoring case). 
This variant of a£qStr allows the second parameter to be a constant.} 

PROCEDURE SUTrirnLeadlng (S: SUStrP); {ff 2/29/84} 

{ SUTrirnLeadlng removes the leading blanks and tabs in the passed 
string. } 

PROCEDURE SUTriraTrailing (S: SUStrP); {ff 2/29/84} 

{ aJTrimTr ailing removes the trailing blanks and tabs in the passed 
string. } 

PROCEDURE SUTrlmBlanks (S: SUStrP); 

{ SUTrlmBlanks removes leading and trailing blanks and tabs in the 
passed string. } 

PROCEDURE SUAddCh (S: SUStrP; Ch : CHAR; MaxStrLeng : INTEGER; 
VAR OverFlow : BOOLEAN); 
{ ^AddCh appends the passed ch to the end of the passed string. 
OverFlow is set to TRUE if adding the ch will cause the string to be 
longer than MaxStrLeng. } 

PROCEDURE SUConcat (SI: SUStrP; S2: SUStrP); 

{ SUConcat appends the second passed str to the end of the first passed 
string. It Is assumed that the target string is of sufficient size to 
accomodate the new value. } 

PROCEDURE SUAddStr (SI: SUStrP; S2: SUStrP; MaxStrLeng : INTEGER; 
VAR OverFlow : BOOLEAN); 
{ ^JAddStr appends the second passed str to the end of the first passed 
string. OverFlow is set to TRUE if adding the second string will 
cause the resulting string to be longer than MaxStrLeng. } 
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PROCEDURE SUSetStr (Dest: SUStrP; Src: SUStrP); 

{ SUSetStr sets the target string (Dest) to the given value (Src) by 
copying the value onto the target. It is assumed that the target 
string is of sufficient size to accomodate the new value. } 

PROCEDURE SUCopyStr (Dest: SUStrP; Src: SUStrP; Start, Count: INTEGER); 
{ aXopyStr sets the destination string (Dest) to the specified 
substring of the source string (Src) by copying the appropriate part 
of the source to the destination. It is assimed that the destination 
string is of sufficient size to accomodate the new value, and that the 
Start and Count values are reasonable. } 

{=s,==s=ssssssass==ss3aisssa=sssssa FILE N(V€S =ass:s=sssssss==sassssss======s3s j 

FUNCTION SUIsVolNaroe (FN: SUStrP): BOOLEAN; 
{ SUIsVolNsme returns a boolean indicating whether the passed file name, 
FN, is a volume or device name (i.e., not a full file name) } 

PROCEDURE SUVolPart (PathN: SUStrP; VolN: SUStrP); {ff 2/29/84} 

{ SUVolPart extracts the volume name part of a pathname (or catalog 
specification). } 

PROCEDURE SUftddExtension (FN: SUStrP; DefExt: SUStr; 

MaxStrLeng: INTEGER; VAR OverFlow: BOOLEAN); 
{ aJAdcExtension will add the default extension, DefExt, to the end of 
the file name, S, if the extension is not already present. If the 
file name ends with a dot, the dot will be removed and no extension 
will be added. If the pathname is a device or volume name only no 
extension will be added. OverFlow is set true if adding the extension 
will overflow the string (determined using MaxStrLeng). } 

PROCEDURE SUSplitFN (PathN: SUStrP; CatN: SUStrP; FN: SUStrP; 
Ext: SUStrP); 
{ SUSplitFN splits a PathName into its catalog, file name, and file 
nane extension ccraponents. } 

PROCEDURE SUMakeFN (PathN: SUStrP; CatN: SUStrP; FN: SUStrP; Ext: SUStr; 
VAR OverFlow: BOOLEAN); 
{ aiiakeFN constructs a PatNSarae fram its catalog, file name, and 
file name extension components. The CS CatN's are assumed to have a 
leading "-". OverFlow is set if any of the file name components are 
too long. This procedure will not create a file name over aJiaxPNLeng 
chars long.} 

PROCEDURE SUChkFN (FN: SUStrP; VAR PState: ProraptState; DefVol: SUStr; 
DefFN: SUStr; DefExt: SUStr); 
{ a£hkFN checks a file nane specification, putting result type in 
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PState. If no file name is given^ then DefFN is used. If FN does not 
heve DefExt in it, then the extension is appended. If no voltffne is 
specifed then the DefVol is used. PState is set appropriately: 
PState = SUOptions if '?' is hit to ask for options 

if nothing specified when a default is present 

if default overriden with '\' or if CR with no 

default 

if one or more of the file name components 

overflowed 

otherwise } 



PState 
PState 



SUDefault 
SUNone 



PState = SUInvalid 



PState = SUValid 



PROMPTING 



=} 



PROCEDURE SUGetCh (VAR Ch: CHAR); 

{ SUGetCh reads a character from the console without echoing it and } 
{ without interpreting <cr> as <sp>., as Read (Ch) does. } 

PROCEDURE SUGetLine (S: SUStrP; VAR PState: PromptState); 

{ SUGetLine reads a line from the console a character at a time^ 
performing its o«wn line editing. PState is set appropriately: 
PState = SUEscape if <clear> was hit. 
PState = SUValid otherwise. } 

PROCEDURE SUGetStr (S: SUStrP; VAR PState: PromptState; DefVal: SUStr); 
{ SUGetStr reads a string from the console; it is like SLCIetLine with 
the addition of defaults. PState is set appropriately: 
PState = SUDefault if <cr> only was hit; S is set to DefVal. 
PState = SUEscape if <clear> was the first cheiracter hit. 
PState = SUValid otherwise. } 

PROCEDURE SUGetFN (FN: SUStrP; VftR PState: PromptState; DefVol: SUStr; 
DefFN: SUStr; DefExt: SUStr); 

{ SUGetFN reads a file name from the console, with result type in 
PState. SLOetFN will print out any defaults in brackets (such as 
[FOO] [.TEXT]) before prompting for the file name. If no file name 
is given, then DefFN is used. If FN does not have DefExt in it, 
then the extension is appended. If no volume is specifed then the 
DefVol is used. PState is set appropriately: 
PState = SLEscape if <cle8r> hit 

if '?' is hit to ask for options 

if nothing specified when a default is present 

if default overriden with '\' or if CR with no 

default 

if one or more of the file name components 

overflowed 

otherwise } 



PState = SUOptions 
PState = SUDefault 
PState = SUNone 

PState = SUInvalid 

PState = SUValid 
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PROCEDURE SUGetInt (VflR I: INTEGER; VAR PState: ProroptState; 
DefVal: INTEGER); 
{ SUGetInt reads an INTEGER from the console, with PState set as in 
SUGetStr, except that PState « SUInvalid when a non-numeric is input.} 

PROCEDURE SUWaitEscOrSp (VflR PState: PromptState); 

{ SUWaitEscOrSp prints a message 'Type <space> to continue, <clear> to 
exit.' & waits for the user to hit a <sp> or <clear>, setting PState 
appropriately: 
PState = SUEscape if <clear> was hit 
PState a SUValid if <sp> was hit } 

PROCEDURE SUWaitSp; 

{ SUWaitSp prints a message ('Type <space> to continue.') and waits for 
the user to hit a <sp>. } 

PROCEDURE SUGetChlnSet (VflR Ch: CHAR; Chars : SUSetOfChar); 

{ SUGetChlnSet reads characters from the console (without echoing) until 
a character from the given set is typed. The accepted character is 
echoed and an end-of-line is written. The character matching ignores 
case. } 

FUNCTION SUGetYesNo : BOOLEfiN; 

{ SUGetYesNo prints the message "(Y or N)" and reads characters from the 
console (without echoing) until a 'y', 'Y', 'n', or 'N' is typed. If 
a 'y' is typed "Yes" will be printed followed by an end-of-line; if 
'n' is typed "No" will be printed. The appropriate boolean value is 
returned. } 

FUNCTION aCetBool (Default: BOOLEAN): BOOLEAN; 
{ aJGetBool prints the message "(Y or N) [<default>3" and reads 
characters from the console (without echoing) until a 'y', 'Y', 'n', 
'N', space or return is typed. If a 'y' is typed "Yes" Will be 
printed in the place of the default. If 'n' is typed "No" will be 
printed. If a space or return is typed the default is used. The 
appropriate boolean value is returned. } 

{====«=========»=========«=» ERROR TEXT RETRIEVAL =========«====»===========} 

PROCEDURE SUGetErrText (Err FN: SUStr; ErrN: INTEGER; ErrMsg: SUStrP; 

VAR ErrRet: ErrTextRet); 
{ SLKSetErrText retrieves error message text, given an error nimber and 
and error file to look the error up in. The error file should have 
been generated by the error file processor. SUGetErrText use 
SUSysReset to open the error file. } 

PROCEDURE SUErrText (ErrFN: SUStr; ErrN: INTEGER; ErrMsg: SUStrP); 
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{ SUErrText retrieves error message text, just as does SUGetErrText; 
however, if the text is not obtainable due to a non-SUOk ErrRet value 
from aJErrText, SUErrText will return the string 
"Error message text not available." } 

{sBSsasasxssBssaBsaBsasssasass OEV . SYS. SUPPORT sbssssssssbbsssssbssbssssssss} 

PROCEDURE SUStopExec (VAR ErrNum: INTEGER); 

{ Should be called to stop the current exec file if an error occurs in a 
program running under an exec. Returns any error conditions 
encountered in closing the exec file in the errnum var parameter. 
Informs the shell that the exec file was terminated due to an error. } 

PROCEDURE SUCloseExec (VAR ErrNum: INTEGER); {ff 3/7/84} 

{ Should be called to stop the current exec file only if you want to do 
so without informing the shell that the exec file was terminated due 
to an error. You should probably use SUStopExec unless you have a 
good reason to use this alternate version. } 

PROCEDURE SUInitSysVols; 

{ Initializes "SUIiyProcV" and "SUOsBootV", the name of the volume on 
which my process was created and the name of the volume which the OS 
was booted off of. A message may be printed if there is trouble 
getting this information from the OS. This can be called more than 
once; it will only make the OS calls the first time. ) 

PROCEDURE SUSysReset (F : SUFileP; FN : SUStr; VAR lOStatus : INTEGER); 
{ SUSysReset is for opening system files, and will try the prefix, boot, 
and current process volumes (in that order) when trying to access a 
file. SUSy^eset assumes that the file name FN does not have a volume 
name. SUSy^eset may sometimes have to call SUInitSysVols. } 

<^ssssssssssssBSsssssBS=Bssssss:ss C(3''<IVERSICV^ ssssssssssssbssssssssbsssssbssbb} 

PROCEDURE SUIntToStr (N : INTEGER; S : SUStrP); 

{ aJIntToStr converts an integer into its string form; The string which 
S points to should be of length >= 6 (5 digits + sign). } 

PROCEDURE SULIntToStr (N : LONGINT; S : SUStrP); 

{ SULIntToStr converts an longint into its string form; The string 
which S points to should be of length >= 11 (10 digits + sign). } 

PROCEDURE SUStrToInt (NS -. SUStrP; VAR N : INTEGER; 

VAR estate : ConvNState); 
{ SUStrToInt converts a string to an INTCt^R. Leading and trailing 
blanks and tabs are permitted. A leading sign ['-', '+'] is 
permitted. The estate variable (conversion state) will be set to 
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indicate if the number was valid, if no number was present, if an 
invalid ntrober was specified, or if the number overflowed. } 

PROCEDURE SUStrToLInt (NS .- SUStrP; VftR N : LONGINT; 

Vf« estate : ConvNState); 
{ SUStrToLInt converts a string to a LONGINT. It behaves just like 
SUStrToInt otherwise. } 
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The ProgComm Unit 



1 Inbroduction 

ProgComm is an intrinsic unit in SULib that allows programs to communicate 
with the shell and with other programs. Three basic mechanisms are 
provided: 

• Set-Next-Run Command. A program can tell the Workshop shell what 
to run next. The specified program will be run after the current 
program is done, taking precedence over even an exec file in progress. 

• The Program Return String. The return string can be set by your 
program and accessed from the exec processor (via the RETSTR 
function). This allows exec scripts to be written that make choices 
based on program results. 

■ The Communication Buffer. The communication buffer is a IK byte 
buffer global to the Workshop for communication between programs. A 
set of primitives supporting character- and line-oriented I/O to and 
from the buffer is provided. 

These mechanisms can be used in conjunction with each other. For example, 
a program can write a series of invocation arguments to the communication 
buffer and then tell the shell which program to run next. This second 
program can check the communication buffer to find its arguments. 
Programs can be written so that, by convention, they first check the 
communication buffer for their arguments, and then prompt for input from 
the console only if the arguments are not found in the buffer. 

2 RrogK^fxnm Routines 

This section describes the ProgComm unit interface. 

2.1 Initializflfcion 

The PCInit procedure initializes the ProgComm unit so that a program may 
use it. 

Procedure PCIhit; 

PCInit should be called before using the ProgComm unit. The program's 
return string (RETSTR in the exec language) is initialized to the null string. 

2.2 Set-Next-Run and the Return String 

The PCSetRunCmd and PCSetRetStr procedures let a program set what 
program will run next and pass back a return string to the exec processor. 
The SUStr type comes from the Standard Unit (StdUnit in SULib), which 
provides a number of string-manipulation routines. 
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Procedure PCSetRunCmd (RC = SUSIj); 

PCSetRunCmd lets a program tell the shell what program or exec file to run 
after the current program terminates, allowing program chaining. RC, the 
run command passed to PCSetRunCmd, should be a string with the same 
program pathname or exec file invocation you would give to the Workshop 
Run command. The run command set in this way will take precedence over 
any keyboard type-ahead and over any pending exec file commands. 

If you want to use PCSetRunCmd to run a Workshop tool normally invoked 
from the Workshop menu line, set RC to the two-character string consisting 
of an escape (CHR(27)) and the appropriate menu command letter. This is 
necessary because typing fto invoke the Editor is not always the same as 
saying Run Editor.OBJ. The Run command looks for Editor.OBJ on the three 
prefix volumes, while the E menu command looks on the Workshop boot 
volume first and then on the prefix volumes. (Note that only some items in 
the Workshop menu are actually separate tools that can be Run.) 

Starting to run an exec file while you are already running another exec file 
causes the first one to be terminated so the second can run. This means 
that if exec file A runs program P, and P calls PCSetRunCmd to run exec 
file B, then, when program P terminates, exec file A will also be terminated 
so exec file B can run. Exec file A will not be resumed when exec file B 
has completed. 

Procedure PCSetRetSbr (RS : SUStr]; 

PCSetRetStr lets a program set a return string that can be accessed through 
the exec processor's RETSTR function. This lets exec files make choices 
based on information passed back to the shell by cooperating programs. How 
the return string is used and interpreted is up to you, and depencte on what 
sort of information you want to pass back to the exec processor. 

23 The CorTMTHinicafcion K^er 

The following procedures and functions operate on the communication buffer, 
a IK byte buffer global to the Workshop shell (that is, it stays around 
between program invocations). The buffer can hold any type of information; 
a standard set of functions is provided for Pascallike character- or 
line-oriented access to the buffer. 

Following are some constant, type, and variable declarations from the 
ProgComm interface which relate to the communication buffer. 

CONST 

{ ccwnmunication buffer content types } 

PCNone = -1; { nothing in buffer } 

PCftny = 0; { for FCReset to match any content type } 

PCText = 1; { text, as supported by PCGets & PCPuts } 

PCBufiHax = 1023; {max buffer index, le, bufr is IK bytes } 
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"nrPE 

PCBuftF = *PCBiifr; { pointer to bufr } 

PCBuftr » PACKED ARRAY [O..PCBijfiHax] or CHAR; 
VAR 

PCBufrPtr : PCBufrP; { points to bufr after successful open } 

The communication buffer is given a type when it is opened for writing with 
PCReWrite. This type will be used to determine whether a potential reader 
trying to open the buffer with PCReset will be successful. The intent is to 
prevent reading of the buffer when the contents are not of the type expected 
by the reader. Three predefined constants are provided for buffer-typing: 
PCNone means that the buffer has no contents; PCText means that the buffer 
contains standard text with CR line delimiters; and PCAny matches any type, 
allowing a reader to override the typing mechanism. Other buffer content 
types (such as mouse events) may be defined by users, choosing a number to 
identify the new type that doesn't conflict with the predefined types. The 
only restriction is that communicating programs must have compatible 
conventions. To use the buffer for something other than text, use PCBufrPtr 
to access the buffer (using whatever means of interpretation of the buffer is 
desired). 

The buffer also has an access key, which functions in much the same way as 
the content type (i.e., writers set it and readers must match it to gain access 
to the buffer). The intent of the access key is to prevent programs from 
reading the buffer when they are not the intended recipient. The access key 
should be established by agreement between communicating programs. If a 
buffer writer does not care about preventing unintended access to the buffer, 
the null string can be used for the access key. Note that the access key is 
case sensitive. 

Following are the routines for opening and closing the communication buffer. 

Procedure PCReWrite (V*iteType: INTEGER; Key: SUStr}, 

PCReWrite opens the communication buffer for writing. The content type 
and access key are set. PCBufrPtr is set to point to start of the 
communication buffer. A PCReWrite will override any previous use of the 
buffer; that is, it will flush any previous buffer contents. WriteType should 
be an integer identifying the type of data you plan to write to the buffer. If 
you are planning to use the text-oriented primitives provided, "A^iteType 
should be PCText; otherwise, WriteType should be some integer established 
by agreement between the communicating programs. Key should be a string 
also established by agreement between the communicating programs. A 
useful form of key is one that identifies the intended recipient, so that 
contents left in the buffer are not read inadvertently by programs for which 
they were not intended. 
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Function PCReset (ReatfType: INTE(£R; Key: SUStr): BOOLEAN; 

PCReset opens the buffer for reading. The boolean result will indicate 
whether the open was successful. The open will fail if ReadType does not 
match the type set by the last buffer writer or if Key does not match the 
key set by the last writer. 

Function PCClose (KillBuTT: BOOLEAN; Key.- SUStr): BOOLEAN; 

PCClose will close (or empty) the communication buffer. If KillBufr is true, 
the buffer will be emptied. In general, the buffer can be read more than 
once (by multiple readers) if desired. If a reader is finished with the buffer 
and knows that no one else should read the buffer, PCClose should be called 
with KillBufr set to true. The call to PCClose will fail if the access key 
does not match. PCClose may be used to flush buffers that were written by 
someone else, as long as you know the access key. PCClose may be called 
without calling PCReset or PCReWrite first. 

Z4 Reading from and Vsh-itir^ to the Comminnicaltion Burfer 

The following functions provide a text-oriented buffer facility with Pascallike 
character- and line-oriented reads and svrites. 

Function PCPutCh (Ch: CHAR): BOOLEAN; 

PCPutCh puts a character into the buffer. The boolean result indicates 
whether the operation was successful. It fails if the buffer is full or if the 
buffer was never opened successfully for writing. Note that PCPutCI^CR) is 
equivalent to PCPutLine("). 

Function PCGetCh (VAR Ok CHAR): BOOLEAN; 

PCGetCh gets a character from the buffer. The boolean result indicates 
whether the operation was successful. It fails if the buffer is empty or if 
the buffer was never opened successfully for reading. 

Function PCPutLine (L: SUStr): BOOLEAN; 

PCPutLine puts a line into the buffer. A CR is put in the buffer following 
the string passed to PCPutLine. The boolean result indicates whether the 
operation was successful. It fails if the buffer is full or if the buffer was 
never opened successfully for writing. 

Function PCGetLine (VAR L: SUStr>. BOOLEAN; 

PCGetLine gets a line from the buffer, where a line is the text from the 
current buffer pointer to the next CR or the end of file (whichever comes 
first). The boolean result indicates whether the operation was successful. It 
fails if the buffer is empty or if the buffer was never opened successfully 
for reading. 



1-4 



Lisa S^<stem Softwsare ProgComm 



23 Internal Vitarkshcqa FwK^ion 

You will notice the following function in the ProgComm interface; it is used 
for special-purpose communication between the Workshop shell and various 
Workshop tools. 

Function F»CSheUCnnd (Cmdr INTEGER; Pr SUStrP): BOOLEAN; 

For internal use by Workshop tools only. Don't use this function. 
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3 Interface 

INTERFACE 

USES 

{$U StdUnit } StdUnit, 
{$U ShellComm } ShellConm; 

CONST 

{ communication buffer content types for use with PCReset and PCReWrite } 
PO^one = -1; { nothing in buffer } 

PCAny =0; {for POReset to match any buffer content type } 
PCText = 1; { text^ as supported by PCGet's and PCPut's below } 

PCBufrMax = 1023; { max Bufr index, ie, comra bufr is IK bytes } 

{ cormand constants for PCShellCmd } 

PC_SetReallyStop = 1; { determines if SUStopExec really stops exec 

files } {ff 3/7/84} 

PCjGetReallyStop = 2; 
PC_SetUnSavedEdits = 6960; { tells if unsaved edits are left in the 

editor } {ff 3/12/84} 

PC.GetUnSawedEdits = 8751; 

TYPE 
PCBufrP = ^PCBufr; { ptr to communication buffer } 
PCBufr = PACKED ARRAY [0. .PCBufrMax] OF CHAR; 



VftR 
PCBufrPtr 



PCBufrP; { will point to PCBufr after successful PCReset or 
PCReWrite } 



PROCEDURE PCInit; 

{ PCInit should be called before using the ProgCwnm unit. One effect of 
note is that the program's return string (RetStr) is initialized to the null 
string. } 
PROCEDURE PCSetRunCmd (RC : SUStr); 

{ PCSetRunCmd enables a program to tell the shell what program (or exec 
file) to run after the current program terminates, which allows program 
"chaining". The run command set in this way will take precedence over any 
keyboard type-ahead and over any pending exec file commands. } 
PROCEDURE PCSetRetStr (RS : SUStr); 

{ PCSetRetStr allows a program to set a return string which may be 
accessed via the Exec Processor's FCTSTR funciton. This allows exec files to 
make choices based on information passed back to the shell by cooperating 
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pcrogrsins. How the return string should be used and interpreted is up to you^ 
and will depend on what sort of information you want to pass back to the exec 
processor. (But in order to be a good citizen it is probably best to follow 
whatever system-wide conventions emerge and prevail.) } 

{ The following procedures and function operate on the COMMUNICATION BUFFER, 
which is a IK byte buffer which is global to the Workshop shell. The buffer 
can hold essentially any type of information, but a standard set of functions 
is provided for Pascal-like character or line-oriented access to the buffer. 

The communication buffer is given a TYPE when it is opened for writing 
with PCReWrite. This type will be used to determine whether a potential 
reader trying to open the buffer with PCReset will be successful. The intent 
is to prevent reading of the buffer when the contents aare not of the type 
expected by the reader. Three predefined constants are provided for buffer 
typing (PCNone which means the buffer has no contents; PCText which means that 
it has standard text with CR line delimiters; and PCAny which will match any 
type, allowing a reader to override the typing mechanism) . Other buffer 
content types (such a mouse events) may be defined by users, choosing some 
number to identify the new type which does not conflict with the predefined 
types. We make no attempt here to provide a complete set of predefined types; 
the issue is simply one of having ccmipatible conventions (agreement) between 
coranuni eating programs. To use the buffer for something other than text, the 
variable PCBufrPtr may be used to access the buffer (using whatever means of 
interpretation is desired). 

The buffer also has an ffiXESS KEY, which functions in very much the 
same way as the content type (ie, writers set it and readers must match it to 
gain access to the buffer). The intent of the access key is to prevent 
programs from reading the buffer when they are not the intended recipient. The 
access key, again, is scmething that should be established by agreement 
between the communicating progrems. If a buffer writer does not care about 
preventing unintended access to the buffer, the null string can be used for 
the access key. Note that the access key is case sensitive. } 

PROCEDURE PCReWrite (WriteType : INTEGER; Key : SUStr); 

{ PCReWrite opens the buffer for writing. The contents type and access 
key are set. PCBufrPtr is set to point to the ccMwnuni cation buffer. } 
FUNCTION PCReset (ReadType : INTEGER; Key : SUStr): BOOLEAN; 

{ POReset opens the buffer for reading. The boolean result will indicate 
whether the open succeeded. The open will fail if contents type and access 
key do not match the type and key set by the last buffer writer.} 
FUNCTION PCClose (KillBufr : BOOLEAN; Key : SUStr): BOOLEAN; {ff 2/2/84} 
{ PCClose will close the buffer. If KillBufr is true the buffer will be 
emptied. In general, the buffer can be read more than once (by multiple 
readers) if desired. If a reader is finished with the buffer and knows that 
no one else should read the buffer, PtXlose should be called with KillBufr set 
to true. The call to PCClose will fail if the access key does not match. } 
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FUNCTION PCPutCh (Ch : CHAR) : BOOLEAN; 
{ PCPutCh will put a character into the buffer. The boolean result will 
indicate whether the operation was successful. It will fail if the buffer is 
full or if the buffer was never opened successfully for writing. } 

FUNCTION PCGetCh (VftR Ch : CHAR) : BOOLEAN; 

{ PCGetCh will get a character from the buffer. The boolean result will 
indicate whether the operation was successful. It will fail if there is 
nothing more to read or if the buffer was never opened successfully for 
reading. } 

FUNCTION PCPutLine (L : SUStr) : BOOLEAN; 

{ PCPutLine will put a string into the buffer, follcwed by a CR. The 
boolean result will indicate whether the operation was successful. It will 
fail if the buffer is full or if the buffer was never opened successfully for 
writing. ) 

FUNCTION PCGetLine (VAR L : SUStr) : BOOLEAN; 
{ PCGetLine will get a line from the buffer. The boolean result will 
indicate whether the operation was successful. It will fail if there is 
nothing more to read or if the buffer was never opened successfully for 
reading. | 

FUNCTION PCShellCmd (Cmd : INTEGER; P : SUStrP): BOOLEAN; {ff 3/7/84} 
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About This Manual 

This manual desta'ibes QuickPort, a set of private and intrinsic units that 
facilitate porting Pascal programs to the Lisa desktop. This manual is 
written for experienced Lisa Pascal programmers who are already familiar 
with the Lisa Workshop and the Lisa Operating System and who understand 
the concepts and conventions used by the Lisa User Interface. In addition, 
those who intend to write terminal emulators are assumed to know Clascal. 

For material not covered in this manual, refer to one of the listed documents 
for additional information: 

- C^y&rating System Reference Manual for the Lisa. 

■ Workshc^ User's Guide for the Lisa 

■ Lisa Internals Manual. 

■ Lisa User lnt&rfax:e Guidelines. 

- /^ If^oduction to Clascal. 
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Ll What is QuickPart? 

QuickPort is a set of private and intrinsic units that provide a fast and 
reliable way to run Pascal programs in the Lisa Office System. By using 
QuickPort, you can make a few changes in a typical Pascal program, and it 
will run on the Lisa desktop. f=ipplications that use QuickPort are integrated 
so that you can cut and paste to and from other Lisa applications. 
QuickPort also provides standard menus for all applications that use it. 

IJZ Types of QuickPart Applications 

Before you can use QuickPort to port your application to the Desktop, your 
program must 

• Run in the Lisa Workshop. 

■ Use only readlns and writ el ns for text input and output. 

A Pascal program that runs in the Lisa Workshop and uses readlns and 
writ el ns for text input and output is called a "vanilla" Pascal program. 
Vanilla Pascal programs can be ported to the desktop with very few changes. 

You can also use QuickDraw calls for graphics, use the mouse to get input, 
and use a subset of the Lisa Hardware Interface. However, the addition of a 
graphic panel and use of the hardware interface involves more coding to 
acheive the port than a vanilla Pascal program. 

13 Additional Festires 

QuickPort also provides a set of additonal procedures for configuring the 
panels, text output, graphic output, and for applications that use the hardware 
interface. Using these features, you can increase the power of your 
application. The additional QuickPort features are described in Chapter 3. 
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2.1 QuickPdrt Program Requirements 

Vanilla Pascal programs need nothing but the addition of one or two list 
elements to the USEs statement in its main program. A vanilla Pascal 
program runs in the Lisa Workshop and uses only readlns and mritelns for 
input and output. You can use QuickDraw^ but there are some minor changes 
required. See Section 3.4.1.1, QuickDraw Requirements, in Chapter 3, for 
more information. If you use the Lisa Hardware Interface, you must modify 
your program and use the QuickPort Hardware Interface. The QuickPort 
Hardware Interface is a subset of the Lisa Hardware Interface; it is described 
in Section 3.11, Procedures for the QuickPort Hardware Interface, in Chapter 
3. 

If your program is a vanilla Pascal program, you can either enhance it using 
the QuickPort features described in Chapter Three, or port it directly to the 
Lisa Desktop. If you wish to port your program to the Lisa Desktop without 
using any of the additional QuickPort features, make sure your program 
works in the QuickPort execution environment described in Section 2.3, and 
then turn to Chapter Four: Bringing Your Application to the Lisa DeskTop. 

2.2 Ctmices for QuickPort Applications 

You can produce several different types of applications using QuickPort: 

■ Applications that produce text output only. 

• Applications that use QuickDraw to produce graphic and/or text output. 

■ Graphic applications that use the QuickPort Hardware Interface to get 
mouse input in the graphic panel. 

QuickPort provides three panels: the text panel, the input panel, and the 
graphic panel. The text panel saves all text output, unless the Don't Save 
Buffer command is chosen from the Edit menu. Any application that 
produces text output only gets a text panel automatically. The input panel 
displs^ text that has not been read by the program. You can choose to 
have the input panel or not; the default is no input panel. Any application 
that produces graphic output only gets a graphic panel. Such programs can 
use in addition, a text panel, and/or an input panel. The default is one 
paneL 

The text and graphic panels can both be scrolled vertically and horizontally. 
The panels can be enlarged and shrunk to provide different views of the 
output. Both panels can be split vertically and horizontally, allowing the 
user to see different parts of the output at the same time. 
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23 The QuickPdrt Execution EnwJrcwHnent 

One of the most impratant things to rennember when using QuickPort is theft, 
the Lisa Desktop is a multiprocessing intergrated environment and you can 
affect the state of other applications running on the desktop if you don't 
keep this in mind. Be particularly careful about using functions in the 
QuickPort Hardware Interface, because these functions change the state of 
hardware, thus affecting all applications (including the desktop). 

QuickPort programs can be run in the background (inactive window) when 
they are not waiting for input. When a progp'am running in the background 
needs input, it is suspended. Programs running in the background compete 
with the active window for CPU time. Programs with long CPU-bound loops 
should use either Yield_CPU or OPYield_CPU to yield the CPU to the 
active window. ~ 

User actions such as pulling down the menus and clicking the mouse are 
processed only when your program calls call screen I/O (WRITES and REffi>s, 
etc.). If you have a long CPU-bound loop, be sure to use either YieldjCPlI 
or OPYieldjCPU, so that your program will be more responsive to the user. 
If you have a tight loop, there is no way for the user to break out of the 
loop, unless the debugger is loaded and you can hit the NMI key to halt the 
process. Be sure to put Yield_CPU, CPYieldjCPU, or PAbortFlag in any 
tight loops. Note that you must call OPConfig to pass an ^-period to your 
program if you need to call PAbortFlag. C^onf ig is described in Section 
3.6 of Chapter 3. 

23.1 Using Operating System Calls 

You can make any operating system calls, but remember that Lisa has a 
multiprocessing environment. Whenever a document is opened, a process 
may be created (tools that handle multiple documents create one process 
that handles one or more documents). If two documents are opened from the 
same tool, you have two processes running separate instances of the same 
program. This could result in inconsistent data if WriteJDatas and 
Read_Datas, cor Rewrites and FSESETs are performed on the same file. If 
this is undesirable, you should add additional code to your application to 
check whether the file can be opened by more than one process. 

23.1.1 Yield_CPU 

Yield_CPU gives the CPU to any other ready process, but does not handle 
any user actions, such as pulling down menus, and moving windows. 
QuickPort pro-vides an alternative procedure, OPYi el d_CPU, that allows the 
user to pull down menus and move the windows around. 

23.1.2 r^^takejprcM^ss 

If you call nakejprocess in a QuickPort application, the resulting processes 
cannot do any screen input and output. 

23.13 LDSIMs (Logical Data Segment Numbers) 

You cannot use a logical data segment number less than 5, or larger than 11. 
Note that LDSN 5 is, by default, used by the Pascal heap. If you use a 
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Pascal heap larger than 128K bytes^ LDSN 6 and up will be used for the 
heap. You can use PLInitHeap to change the Pascal heap to a different 
LDSN, but make sure you don't collide with the system LDSNs. 

- LDStsIs 1-4 ~ QuickPort 

- LDSN 5 ~ Default Pascal heap 

-LDSN 11 — OPEN '-printer', RESET, or REWRITE -printer' 

" LDSNs 12-16 ~ LisaLibraries 

23.1.4 Tc9riTiinal;e_PrcK;ess, KiU_Process 

QuickPort programs should not call Tennin€te_ft-ocess or Kill_Process. 
These calls will terminate the program, leaving the user with no chance to 
do anything with the output. If you need to terminate program execution, 
use halt or drop through to the end statement of your program. 
♦♦♦PROGRAM TERMINATED*** will appear on the screen, and the user will 
be able to save and put away, copy, or print. 

23.13 Terminating the Rri^wn ^^bnarrradly 

TrnntExceptionHandler is the standard QuickPort exception handler for 
abnormal termination of a program. You can write your own terminate 
exception handler, but you must call TrnntExceptionHandler immediately 
in your exception handler. If this call is not made, the system will hang 
because QuickPort will not have a chance to clean up and transfer control to 
the desktop manager. 

2.4 The QuickPcrt User Interface 

QuickPort provides a standard user interface for its applications that is, with 
the exception of a few menu commands, the same as the standard Lisa user 
interface. Manipulating windows and using the mouse follow the standard 
Lisa user interface, as do opening and closing documents. 

QuickPort provides some menu commands that are different from the 
standard Lisa menu commands. These commands allow the user to control 
program execution. A standard Lisa application continuously loops to get and 
process events. A QuickPort program, however, may run from beginning to 
end. When a QuickPort program reaches its end, it will not respond to input 
from the keyboard, and its window will remain open to allow the user to 
view the output. At this stage, the QuickPort application is idle, waiting for 
one of the following menu commands: 

■ Set Aside ~ Places the document (without saving) in its icon on the 
desktop. If the document is reopened, the application will still be idle. 

■ Save & Put Away — Saves the document. The process is then 
terminated. If this document is opened again, the program will not run 
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immediately — it is waiting for the Restart command. If the user 
wants to browse through the document^ it is not necessary to use the 
Restart command. Instead, use Save & Put Away, or Set Aside. 

■ Restart ~ Restarts program execution. 

QuickPort applications are started, from the desktop, by tearing off a 
document from the stationery pad and opening the document. 

The QuickPort menus are discussed in Appendix A. 
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3.1 Introduction to the Features 

QuickPort provides a set of features that you can use to enhance your 
application. The additional procedures and functions are for 

■ Configuring the text and graphic panels. 
- Controlling text output. 

■ Handling graphic output using the mouse for input. 
" Providing printer support. 

■ Using the QuickPort hardware interface. 

■ Making use of the terminal emulators. 

You can combine any of these procedures and functions within a QuickPort 
application. 

You can also write your own terminal emulator. To do this you must know 
enough Clascal to understand subclasses, methods, and overriding methocfs. 
Read An Introduction to Clsscal before attempting to write your own 
terminal emulator. See Appendix B, Writing Your Own Terminal Emulator for 
more information. 

The logical device, '-printer', behaves in much the same way as it docs in 
the Workshop, but also interacts with the Desktop's print manager. A section 
on printer support i^ included in this chapter. 

32. Text Input and the Input Panel 

QuickPort programs get input in two ways: from the keyboard, and from the 
clipboard. The input panel displays the text that has not yet been consumed 
by the program. Text in the input panel comes from two sources: "type 
ahead" text (text which is entered from the keyboard too quickly to be 
echoed immediately by the program), and text from the clipboard that will be 
"pasted" into the text window. The 'Read Input from Clipboard' command 
places the selected text in the input buffer. When the program does a read, 
the text in the input buffer is read f irstd. If the input buffer is empty, the 
read waits for input from the keyboard or from a paste command. 

33 Text Output and the Text Ponei 

The text output panel displays the writeln output from the program. The 
text panel corresponds to the Pascal device output and the logical device 
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'-console'. The text panel emulates a terminal display. The default size of 
the sca^een area is 24 lines by 80 columns. The width of the text panel can 
be changed either by the program, or by the user from the Setup menu. The 
Setup menu is described in Appendix A. 

The text panel has a buffer area that saves text as it is scrolled above the 
screen area. The size of the buffer area is increased automatically as lines 
are saved. The size of the buffer is limited to the amount of memory 
available to increase the size of the buffer. When the buffer size reaches 
its limit, the lines scrolled off the top of the buffer area will not be saved. 
The limit is approximately 3500 80-character lines. The user can choose to 
save or not save scrolled output using the Setup menu. The Edit menu is 
described in Appendix A. 

The screen area hss a cursor that is affected by readlns and mritelns 
from the program. The cursor position is always: 

" Inside the screen area. 

■ Relative to the top left position of the screen area. 

The cursor position is the insertion point for input. No menu commands 
change the logical cursor position; it is controlled solely by the program. 
The cursor position is always visible when there is a read from the program. 
In other words, if the panel has been scrolled so that the cursor position is 
hidden, QuickPort scrolls back to the cursor position when encountering a 
read. The cursor home position is the top left position of the screen area. 

3.4 Graphic OutfHA, the Qrafihic Panel, and Mouse Input 

Graphics in QuickPort applications are created by QuickDraw. QuickPort 
provides an option that allows you to choose two panels, one for text output 
and one for graphic output, or one panel for both text and graphic output. 
The graphic panel corresponds to the Workshop screen. The screen size is 
720 pixels wide and 364 pixels high. The entire graphic panel is equal to 
the screen area in the text panel. There is no buffer area in the graphic 
panel because graphic output will not be scrolled out of the graphic panel. 
All graphic objects created by the program are saved in the graphic panel 
using a QuickDraw picture. 

In the text panel, the mouse is used to select text. In the graphic panel, 
mouse clicks are saved and passed to the program. Whenever the mouse 
button is pressed inside the graphic panel, a mouse event, MouseDown,. with 
the mouse location is saved. When the mouse button is pressed while the 
mouse is moved, another mouse event, with different locations, is saved. 
When the mouse button is released, a mous^p event is saved. To see if 
there are any mouse events in the queue, call HouseEvent. HouseEvent 
returns one event at a time, until there are no more mouse events in the 
queue. When HouseEvent is called, if the mouse button is down, control 
will not be returned to the caller until the button is released. For this 
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reason, VGetMouse should not be used after a call to HouseEvent, because 
the mouse may be moved. Each mouse event stores a mouse location 
indicating where the mouse button was pressed. VGetMouse lets you track 
the mouse location when the mouse button is not down. 

For more information on MouseEvent, Refer to Section 3.8.1.3. 

3.4.1 QMckDraw Requiren^nts 

Pascal programs that run in the Lisa Workshop and use QuickDraw, call 
QDINIT and OpenPort (in the QD/Support unit). To use QuickDraw you must 

" Remove the call to QDINIT and OpenPort. QuickPort initializes 
QuickDraw and opens a grafPort for drawing to the graphic panel. 

• Not open a picture in this grafPort since QuickPort uses a picture to 
save the graphic output. 

■ Not customize low-level QuickDraw drawing routines in this grafPort. 

If your program needs to use pictures, you can open a picture in another 
grafPort. If your program needs to redefine any of the QuickDraw low-level 
routines, you can do this in another grafPort. If your application uses 
multiple grafPorts, you must switch to the QuickPort grafPort whenever you 
want to draw to the screen. 

If your application calls DrawPicture, you must call another QuickDraw 
drawing routine before calling DraMPicture. This is because QuickPort 
opens the picture when the first QuickDraw drawing routine is encountered. 
If DrawPicture is the first drawing routine encountered, QuickPort 's picture 
will be opened incorrectly because QuickPort can handle only one picture at 
a time. Here is an example showing how to avoid such collisions: 

GetPort (sysportptr); {saves system port} 
Operd^ort (inyPort); {references alternate port} 
nyPlcture == OpenPicture (thePorf^.portRect); 

. . . make your QuickDraw calls here . . . 

ClosdPlcture; 

SetPort (sysportptr); {snitches to systen grafPort} 

EraseRect (thePort*.PortRect); {opens systen picture 

— any drawing routing can 

be used) 
DrawPicture (iiyPicture^ thePorf.PortRect); 
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If you call OpenPicture while the QuickPort grafPort is the current port, 
the following alert message appears on the screen and the program is 
aborted: 

Your QuickPort tool has called another Opertf^icture inside 
the QuickPort grafPort. This tool will be aborted. 

The QuickDraw procedure ScrollRect is not supported by QuickPort. 
ScrollRect is not supported because QuickPort uses a picture to sa</e the 
graphic output, and the effect of ScrollRect is not saved in a picture. 
This means that if the user scrolls the window, the picture is redrawn to the 
window as if ScrollRect had not been called. 

The size limit for the QuickPort picture is 32K bytes. When the picture 
approaches this size, an alert is displayed. Subsequent graphic output is 
displayed on the screen, but is not sawed in the picture. As the size of the 
picture increases, the redrawing that happens as the picture is scrolled or the 
window moved slows. You can find out the current picture size by calling 
QPGrafPicSize. Once the picture size reaches 32K bytes, the only way to 
save the remaining graphic output is to ErasdRect the entire screen 
(thePort^.PortRect). The effect of this call is to delete the old picture 
and create a new picture. 

You can draw bit images in the QuickPort grafPort. The entire gB'aphic panel, 
including the bit images, can be printed. You can copy the bit images to a 
LisaWrite document, but you cannot copy bit images from a QuickPort 
application to a LisaDraw document. 

33 Required Change to Your Program 

Before you can call any of the additional QuickPort procedures, you must add 
UOPortCall to your USES list: 

{$U QuickDraw} QuickDraw, 

{$U QP/UQPortCall} UOPortCall, 

{$U QP/UQuickPort} UQuickPort; {or UQPortGraph, or 

UQPortVTlOO, or UQPortSoroc} 

3.6 R-ocefftjres for all ^^licafcions 

3.6.1 ConTiguring the Panels — QPConfig 

You can choose several different ways to orient the panels in QuickPcat 
applications. The procedure (PConf ig lets you rearrange the panels and 
their orientations. Figure 1 shows some of the different layouts. 



3-4 



QuickPort Proc^amm&r's Guide 



f^cKf&ioed (PifickPort Fea^t^es 



IbSi^apyB 



input panel 



text panel 



graphic panel 



D 



Ibasic paperl 



input panel 



text panel 



graphic panel 



input panel 




graphic panel 



text panel 





input panel 


graphic panel 


text panel 



Fi^jre 1. 
QufckPfxt Window LavYiuts 

Call the OPConfig procedure from your main program before any screen 
input and output is performed. You must set all the fielcte of a global 
variable of type TQPConfigRec. 

PROCEDURE OPConfig (config = TOPConfigRec); 

where 



TOPConfigRec » RECORD 

tosaveBuffer : BOOLEAN; {save lines in 
buffer} 

BOOLEAN; {pass apple '.'to 
nain prograM} 
BOOLEAN; {display input 
panel} 

BOOLEAN OF {have both text 
and graphic panels} 



passAppl ePeri od 
showInputPanel 
CASE tifoPanels 
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TRUE : (vhs : VHSelect; {vertical or 

horizontal split. VHSelect 
is defined in QuicicOraM} 

grPanelSize : INTEGER); {initial width or 
height in pixels, if < 0, 
text panel is below or right 
of the graph panel} 



END; 



If OPConf ig Is not called, the default values are used. These defaults are 
in effect only if OPConf ig is never called. If you call OPConf ig you must 
set all fields, or else they will be undefined.. The default values are: 

tosaveBuffer false 

passApplePeriod false 

showInputPanel false 

twoPanels false 

The graphic and text panels can be oriented in several different ways on the 
screen. To use OPConf ig to set up the panels, you must first declare a 
variable of type TCFConfi^ec. For example. 



VAR 

MyConfig: TOPConfi^ec; 



OPConf ig(MyConfi g ); 



To have both a graphic and a text panel, twoPanels must be TRUE. You 
must initialize the vhs field if you set twoPanels to TRUE. Once you have 
two panels, you can choose to split the windows on the screen vertically or 
horizontally. Refer to Figure 1 to see what the screen looks like with 
vertical and horizontal splits between windows. Then you can set the 
grPanelSize field to the size you want the graphic panel when the 
document is first opened (the text panel will take up the remaining space in 
the window). 
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If CV^onfig is not called^ the default values are used. Programs that 
handle only text output have a default of one text panel. Programs that 
handle graphic output have a default of one graphic panel. 

3.7 RrGK^dures for U^ing the Text Panel 

The procedures for QuickPort applications that produce text output allow you 

tO: 

■ Change the terminal parameters. 

■ Get raw input from the console. 

■ Clear the screen. 

• Control the cursor. 

■ Set and clear tai3s. 

■ Control keyboard input. 

• Change the character style. 

3.7.1 Changing the Terminal Parameters ~ SetupTeraPara 

SetupTemPara sets the terminal parameters for the screen area in the text 
panel. You can call SetupTemPara from your terminal emulator or from 
your main program, but the call must be made before any screen input or 
output is performed. If SetupTernPara is not called before performing 
screen input or output, the default parameters will not be changed. If you 
call SetupTerrf^ara you must set all parameters. 

PROCEDURE SetupTemPara (tempara : TTeraPara); 

where 

naxPosLines = 50; {nax possible lines for any 

terninal enulator} 
naxPosColunns - 132; 

Tcursor shape = (blockshape, underscoreshape, 
invisibleshape); 

TTemPara = RECORD 

roHsize : l..inaxPosLines; 

columnsize : l..iiaxPosColuiins; 

toWraparound : BOOLEAN; 

keytoStopOutput : CHAR; 

keytoStartOutput : CHAR; 

tncursorShape : Tcursorshape; 

EM>; 
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If SetupTernPara is not called^ the default values are used: 

rowsize 24 lines 

coliMnsize 80 columns 

toMraparound TRUE 

keytoStopOutput #-S 

keytoStartOuiput df-Q 

tacursorShape Block 

3.7J2 Getting Raw Input from the Console — Vread 

You can use Vread instead of read to get keyboard input and the control 
keys. Vread does not echo characters as they are read. 

PROCEDURE Vread (VAR ch.- CHAR; VAR keycap = QPByte; 

VAR applekey, shiftkey, 
optionkey: BOOLEAN); 

The keycap is useful when you need to distinguish the numeric keypad from 
the main keyboard. Refer to Section 3.11.4 for the keycap definition. Note 
that the option key is typically used to generate extended Lisa characters. 
The extended Lisa characters are those characters in the range above ASCII 
127. Try not to use the option key for other purposes to avoid confusing the 
users. 

3.73 Qearing the Screen — ClearScreen 

ClearScreen provides six different ways to clear all or part of the screen. 
The six ways are: 

• Clear the whole screen. 

• Clear from the cursor position to the end of the screen. 

■ Clear from the beginning of the screen to the cursor position. 

■ Clear the whole line. 

■ Clear from the cursor position to the end of line. 

■ Clear from the beginning of the line to the cursor position. 
PROCEDURE ClearScreen (clearkind : INTEGER); 

{clearkind definition for ClearScreen procedure} 

sclearScreen « 1; {clear the whole screen} 

sclearEScreen = 2 {clear to the end of the 

screen} 
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sclearBScreen - 3 


{clear from the beginning 




of the screen to the cursor 




position} 


scl ear Line « 4 


{clear the whole line} 


sclearELine - 3; 


{clear to end of line} 


scleazfiLine » 6; 


{dear from the beginning 




of the line to the cursor 




position} 



3.7.4 Conljolling the CiMSor — VGotoxy and MoveCursor 

3.7.4.1 VGotoxy 

VGotoxy moves the cursor to a specified position in the window. 

PROCEDURE VGotoxy (x^ y = INTEGER); 
VGotoxy is the same as the Pascal gotoxy, but faster. 

3.7.4.2 MoveCtssor 

HoveCursor moves the cursor to a position in the window relative to the 
current cursor position MoveCursor allows vertical scrolling only. 

PROCEDURE HoveCursor (scroll : BOOLEAN; xdistance^ 

ydistance : INTEGER); 

For the xdistance, ydistance parameters: 

" A positive value moves the cursor to the right or down. 

■ f\ negative value moves the cursor to the left or up. 

If the cursor is moved down, and scroll is TRUE^ the output will be 
scrolled up. 

3.73 Setting and Cteering Tabs — - SetTab and ClearTab 

3.73.1 SetTab 

SetTab sets a tab at a specified column^ or at the current cursor position. 

PROCEDURE SetTab (colunn : INTEGER); 

SetTab sets tab at current cursor position if colunn <0. 

3.732 QearTA 

ClearTab clears a tab at a specified column, or at the current cursor 
position. 

PROCEDURE ClearTflii (dearftll : BDOLEflN; coltMn : INTEGER); 

ClearTab clears tab at current cursor position if coluan <0. 
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3.7 JEt CcNrUxoUirQ Keyboard Input — Stoplnput and St art Input 

3.7.6.1 Stoplnput 

Stoplnput prevents recognition of keyboard input until Startlnput is 
called. 

PROCEDURE Stoplnput; 

3.7.6.1 Startlnput 

Startlnput allows recognition of keyboard input. 

PROCEDURE Startlnput; 

3.7.7 Changing the Clraradtar Style — ChangeCharStyle 

ChangeCharStyle changes the character attributes to any style combination 
defined by QuickDraw. 

PROCEDURE ChangeCharStyle (newstyle : Style); 

3.8 Fhrocedu-es for Using the GrapMc Panel 

The procedures for QuickPort applications that produce graphic output allow 
you to use the mouse to get input. These procedures are: 

• Get the current mouse location. 

■ Test to see if the mouse button is up or down. 

■ Get a mouse event. 

■ Get either mouse or keyboard input. 

3.8.1 Mouse Routines 

The mouse routines listed in this section should be used instead of the ones 
in the Lisa Hardware Interface. 

nouseEvent is a polling function. Programs may loop on MouseEvent to 
wait for mouse input. This unnecessarily takes up CPU time. Also, if the 
application is run in the background, MouseEvent will force it to run 
periodically, just to find out there is no mouse input, and then control is 
returned to the active window. This slows down the execution and user 
response in the active window. 

WaitHousdEvent is a blocking procedure. HaitHouseEvent will not retiorn 
to the caller until there's a mouse event, allowing user actions to be 
processed immediately when there are no mouse events. When a program 
that uses WaitHouseEvent is in the background, it is suspended and 
consequently, does not take CPU time from the active window. 

3.8.L1 VGetnouse 

VGetMouse returns the current mouse location in the coordinates of the 
current grafPort. 

PROCEDURE VGetHouse (VAR pt : Point); 
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Point is a type defined in QuickDraw. Refer to The Lisa Pascal Reference 
Manual, Appendix C, QuickDraw for the definition of Point. 

3J&.12 MouseButton 

HouseButton returns the current state of the mouse button. 

FUNCTION MouseButton : BOOLEAN; 

3.8.13 HouseEvent 

NouseEvent returns a mouse event if there is one in the queue, and returns 
FALSE if there is not a mouse event in the queue. A mouse event is: 

■ A mouse buttondown (when the user presses the mouse button). 

■ Mouse motion while the button is pressed. 

■ A mouse buttonup (when the user releases the mouse button). 

Moving the mouse without, pressing the mouse button is not a mouse event. 
When HouseEvent is called, if the mouse button is dov/n, control will not be 
returned to the caller until the button is released. 

FUNCTION HouseEvent (VAR aMouseEvent : THouseEvent) 

: BOOLEAN; 

where 

THouseEvent =» RECORD 
nouseLoc : Point; 

clicknun : INTEGER; {nax 3 for triple clicks} 
nouseDoMn, neShift^ meApple, neOption : 
BOOLEAN; 

END; 

For each mouse down event (nouseOown = TRl^), several different 
nouseLoc events may be returned in subsequent calls. These mous^oc 
events are always ended with a mouse up event (mouseDown = FALSE). 

For a double click, HouseEvent returns events of down, up, down, up with 
the clicknun for the second mouse down event equal to two. If the mouse 
button is pressed twice, but the presses do not constitute a double click, the 
same sequence of events is returned, but with the clicknim for the second 
mouse down event equal to one. 

For a triple click, HouseEvent returns events of down, up, down, up, down, 
up, with the clicknun foi" the third mouse down event equal to three. 

If the nouseDovfn field is FALSE, all other fields are meaningless. 

HeShift is TRUE if the mouse button and the Shift key are depressed. 
Me Apple is TRUE if the mouse button and the # key are depressed. 
MeOption is TRUE if the mouse button and the Option key are depressed. 
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3.8.1.5 MaitMouseEvent 

Hai tHouseEvent gets a mouse event. HaitMouseEvent blocks the caller 
until there is a mouse event in the queue. 

You should use this call instead of MousdEvent to avoid polling and wasting 
CPU time. HaitMouseEvent also makes a program more responsive to user 
events such as pulling down menus, clicking in other windows, etc., when the 
program is waiting for mouse input. 

PROCEDURE WaitHouseEvent (VAR aMouseEvent : 

THous^vent); 

where 

TMouseEvent - RECORD 

nouseLoc : Point; 

clicknun : INTEGER; {max 3 for triple clicks} 

nouseDoMn, neShift^ ne Apple, neOption : 
BOOLEAN; 

END; 

After WaitHouseEvent returns, a call to MouseEvent will get the rest of 
the mouse events. 

3.8.1.6 WaitEvent 

HaitEvent is a combination of read and WaitHouseEvent, blocking the 
caller until there is either keyboard or mouse input. 

You should use this call instead of HouseEvent and keypress if you want 
both mouse and keyboard input. WaitEvent does not reurn input. You must 
call read, Vread, or HousdEvent depending on the value returned from the 
call. 

PROCEDURE WaitEvent (VAR fronKeyboard : BOOLEAN); 

3-8.1.7 OPGrafPicSize 

OPGrafPicSize returns the size of the picture in the system grafPort. 

nJNCTION CJPGrafPicSize -. INTEGER; 

3.9 Rrinter Support 

The printer is designated -printer by the Workshop, -printer is a logical 
device. To open the printer, use reset or rewrite, passing -printer as 
the file name. To send output to the printer, use writeln or iirite. Use 
close when you're finished sending information to the printer. Close lets 
the printshop manager know that the program is done with the printer and 
causes the last page to print out. If you do not call close after printing is 
finished, the printer is considered in use, and is unavailable to all other Lisa 
applications. 
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The printer is shared lay all applications in the printshop. When you send 
something from a QuickPort application to the printer from QuickPort^ you do 
not get immediate output. First the document is spooled to the printer 
queue by the printshop manager in the Lisa Office System. If there is 
nothing in the queue^ the information comes out a page at a time. If there 
is something in the queue at the time of reset or rewrite^ an error 
message is returned. 

You can change the font the printer uses by calling PrChangeFont. The 
default font is 10-point, 10-pitch Century. 

Paper size, printing orientation and print resolution can be changed using the 
Format for Printing command in the File/Print menu. Selections made using 
the Format for Printing command take effect only after a reset or 
Tcmrite. 

The Print and Print As Is commands in the File Print menu print all the 
output in the selected panel. 

3.10 The TerminQl Emuletos 

QuickPort provides three terminal envirc»iments: the standard terminal, the 
VTIOO terminal emulator, and the SOROC terminal emulator. This section 
summarizes the three emulators. If you want to write your own terminal 
emulator, go to Appendix B, Writing Your Own Terminal Emulator. 

3.10.1 The Standard Terminal 

The standard terminal is the terminal environment QuickPort uses unless you 
specify otherwise. The standard terminal provides a set of screen and cursor 
control functions. The standard terminal does not use escape sequences, but 
does interpret a set of standard control keys at output: BELL, backspace, 
horizontal tab, line feed, and carriage return (without line feed). Programs 
that use reads and readlns will have the backspace key processed 
automatically, i.e., the backspace key will not be passed to your program if 
you use reads and readlns. If your program needs to get the backspace 
key, use vread instead. 

The standard Lisa applications use the #-period combination to terminate 
long operations. QuickPort provides an option that suspends the program when 
the ll-period key combination is detected. The default is to detect the 
^-period combination. This option is passed in OPConf ig, which is described 
in Section 3.6. When a program is suspended, the user can select the 
Resume command to resume program execution, or the Sewe & Put Away 
command to terminate program execution. 

The Setup menu (in all QuickPort applications) lets you select 80 or 132 
columns per line, turn wraparound on or off, and set the tab positions. 

3.10.2 The VTIOO Terminal Emulator 

The QuickPort VTIOO terminal emulattff interprets all VTIOO and VT52 escape 
sequences, with the exception of escape sequences related to host 
communications. When you use the VTIOO terminal emulator, the screen area 
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in the text panel responds to VTIOO and VT52 escape sequences from i«rites 
and MTitelns. 

The character styles supported by the QuickPort VTIOO terminal emulator are 
bold, underline^ and highlight. Since highlighted text in Lisa applications 
traditionally means a selection, highlighted text .in the VTIOO screen area 
v/ill be shadowed. Double-height and double-width characters are not 
supported. 

To use the VTIOO terminal emulator, add 

{$U OP/UOPortVTlOO} UOPortVTIOO; 

to the USES list at the beginning of your main program. For more 
information, refer to Section 4.1, Adding the USES List Elements, in Chapter 
A. 

3.103 The Soroc Terminal Emulfltor 

Pascal programs that run in the Lisa Workshop, and on the Apple II or Apple 
III, use Soroc escape sequences for output display. QuickPort provides a 
Soroc-compatible terminal emulator to help port these applications to the 
Lisa desktop. The QuickPort Soroc terminal emulator interprets all Soroc 
escape sequences, with the exception of those escape sequences related to 
display protection. 

To use the Soroc terminal emulator, add 

{$U OP/UOPortSoroc} UQPortSoroc; 

to the USES list at the beginning of your main program. For more 
information, refer to Section 4.1, Adding the USES List Elements, in Chapter 
4. 

3.11 Procedures far the QuickPort Hardwa-e Interface 

The QuickPort hardware interface is a subset of the Lisa hardware interface. 
These procedures are for the mouse, the screen, the speaker, the keyboard, 
the timers, and date and time. 

To use the QuickPort hardware interface, you must add 

{SU OP/Hardware} Hairdware; 

to the list elements in your program's USES statement. Refer to Chapter 4 
for more information. 

3.11.1 The Mouse 

The mouse procedures let you 

" Set the frequency at which the current mouse location is updated. 

■ Choose the relationship between physical and logical mouse movements. 

■ Count mouse movements. 
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3.11.1.1 Mouse l^KlBite Frequency 

The mouse location is updated periodically, rather than continuously. The 
frequency of these updates can be set by calling h4ousel^ates. The time 
between updates can range from milliseconds (continuous updating) to 28 
milliseconds, in intervals of 4 milliseconds. The initial setting is 16 
milliseconds. 

Procedure MouseUpdates (delay: Milliseconds); 

3.11.1.2 Mouse Scaling 

MouseScaling enables and disables mouse scaling. Mouseltresh sets the 
threshold between fine and coarse movements. 

Procedure MouseScaling (scale: Boolean); 

Procedure MouseThresh (threshold: Pixels); 

The relationship between physical mouse movements and logical mouse 
movements is not necessarily a fixed linear mapping. Three alternatives are 
available: unsealed, scaled for fine movement and scaled for coarse 
movement. Initially mouse movements are unsealed. 

When mouse movement is unsealed, a horizontal mouse movement of x units 
yields a change in the mouse X-coordinate of x pixels. Similiarly, a vertical 
movement of y units yielcte a change is the mouse Y-coordinate of y pixels. 
These rules apply irregardless of the speed of the mouse movement. 

When mouse movement is scaled, horizontal movements ere magnified by 3/2 
relative to vertical movements. This is to compensate for the 2/3 aspect 
ratio of pixels on the screen. When scaling is in effect, a distinction is 
made between fine (small) movements and coarse (large) movements. Fine 
move- ments are slightly reduced, while coarse movements are magnified. 
For scaled fine movements, a horizontal mouse movement of x units yields a 
change in the X-coordinate of x pixels, but a vertical movement of y units 
yields a change of {2/3)*y pixels. For scaled coarse movements, a horizontal 
movement a x units yields a change of (3/2)* x pixels, while a vertical 
movements of y units yields a change of y pixels. 

The distinction between fine movements and coarse movements is determined 
by the sum of the x and y movements each time the mouse location is 
updated. If this sum is at or below the threshold, the movement is 
considered to be a fine movement. Values of the threshold range from 
(which yields all coarse movements) to 256 (which yields all fine movements). 
Given the default mouse updating frequency, a threshold of about 8 
(threshold's initial setting) gives a comfortable transition between fine and 
coarse movements. 
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3.11.U McHJse Odometer 

MouseOdometor returns the sum of the X and Y movements of the mouse 
since boot time. The value returned is in (unsealed) pixels. There are 180 
pixels per inch of mouse movement. 

Function MouseOdometer: MarF/PixelS; 

3.11J2 The Screen 

The screen procedures are used to 

• Set the size of the display screen. 

■ Count the number of screen refreshes. 

■ Set the screen contrast, set automatic screen dimming. 

• Set the fade delay. 

3.6.2.1 Screen Size ~ ScreenSize 

The display screen is a bit mapped disple^'. In other words, each pixel on 
the screen is controlled by a bit in main memory. The display has 720 
pixels horizontally and 364 lines vertically, and therefore requires 32,760 
bytes of main memory. The screen size may be determined by calling 
ScreenSize. 

Rrfx:edure ScreenSize (v&r x: Pixete; var y: Pixels); 

3.11.2J2 Screen Refresh CowAer — FrameCouviter 

The screen display is refreshed about 60 times per second. A frame counter 
is incremented between screen updates, at the vertical retrace interrupt. The 
frame counter is an unsigned 32-bit integer which is reset to each time 
the machine is booted. FrameCounter returns this value. To minimize 
flickering, an application can synchronize with the vertical retraces by 
watching for changes in the value of this counter. The frame counter should 
net be used as a timer; use the millisecond and mircosecond time's instead. 

Fmcticm FrameCounter: Frames; 

3.11.23 Ska-een Contrast — ScreenContrast, SetContrasi and 
RanqiCorrtjast 

The screen's contrast level is under program control. Contrast values range 
from to 255 ($FF), with as maximum contrast and 255 as minimum. 
SoreenContrast returns the contrast setting; SetCwArast sets the screen 
contrast. The low order two bits of the contrast value are ignored. The 
initial contrast value is 128 ($K>). 

Function Contrast: ScreenContrast; 

Procedure SetContrast (contrast: ScreenContrast); 
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A sudden change in the contrast level can be jarring to the user. 
RafT^;»Contrast gradually changes the contrast to the new setting over a 
period of about a second. RampConlTast returns immediately^ then ramps 
the contrast using interrupt driven processing. 

ProcednEe Ran^»Contrast (contrast: ScreenCdntrast); 

3.11.Z4 AutcHTiatic Screen Dimming — DimContrast and 
SetDimContrast 

The screen contrast level is automatically dimmed if no user activity is 
noted over a specified period (usually several minutes). The contrast level is 
dimmed to preserve the screen phospher. DimCcmtrast returns the contrast 
value to which the screen is dimmed; SetDimContrast sets this value. The 
initial dim contrast setting is 176 ($B0). 

Function DimContrast: Sa&BnCortiiBet; 

Procedure SetDimContrast (cmitrast: ScreenCcNitrast); 

3.11..2..5 PUJtomdtic Screen Fading — FadeDelay and SetFadeDelay 

The delay between the last user activity and dimming of the sci-een is under 
software control. FadeDelay returns the fade delay; SetFadeDelay sets it. 
The actual delay will range from the specified delay to twice the specified 
delay. The initial delay period is five minutes. 

Function FaiteDelay: MilliSeconds; 

Procedtre SetFadeDelay (delay: MilliSeccwids); 

3.1L3 The Speaker 

The speaker routines in this section provide square wave output from the 
Lisa speaker. 

The speaker procedures let you 

■ Set the speaker volume. 

■ Use the speaker. 

3.11.3.1 Specdcer Volume — Volume and SetVolinre 

The speaker volume can be set to values in the range (soft) to 7 (loud). 
Volume reads the volume setting; SetVolume sets it. The initial volume 
setting is 4. 

Function Volume: SpeakerVolume; 

Procedure SetVolume (volumer SpedkerVolume]|; 
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3.113^ Using the Speaker — Noise, Silence and Beep 

Noise and Silence are called in pairs to start and stop square wave output. 
Beep starts square wave output which will automatically stop after the 
specified pra-iod of time. The effects of Noise, Silence and Be^ are 

overridden by subsequent calls. 

Procedure Noise (weveLength: Microseconds); 

Procedure Silence; 

Procedure Beep (waveLength: Microseconds; duration: 

Noise produces a square wave of approximately the specified wavelength. 
Silem;e shuts off the square wave. The minimum wavelength is about 8 
microseconds^ which corresponds to a frequency of i25,0(X) cycles per second, 
well above the audible range. The maximum wavelength is 8491 micro- 
seconds, which corresponds to about 122 cycles per second. 

3.11.4 The Keyboard 

Three physical keyboard layouts are defined, the Old US Layout (with 73 keys 
on the main keyboard and numeric keypad), the Final US Layout (76 keys) and 
the ELiropean Layout (77 keys). Each key has been assigned a keycode, which 
uniquely identifies the key. Keycode values range from to 127. Figure 2 
defines the keycodes for the Final US Layout, using the legends from the US 
Keyboard. The Old US Layout has three fewer keys: |V Alpha Ent^, and 
Right Option are not on the old keyboard. The European Layout has one 
additional key, x, with a keycode of $43. 

Two keys on the Old US Layout generate keycodes different from the 
corresponding keys on the^ Final US Layout. To aid in compatibility, software 
changes the keycode for ~' from $7C to $68, and the keycode for Right 
Option from $68 to $4E. 
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Figure 2 
Keycodes for "Final US Layout" 
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The keyboard procedures allow you to 

■ Find out the keyboard identification number. 

■ Find out the state of keyboard. 

3.1L4.1 Keytjoard Identificdtion — Keyboard 

The Lisa supports a host of diff^ent keyboards. Each keyboard has three 
major attributes.- manufacturer^ physical Isi^'Vut, and legends. The chart below 
describes how these three attributes are combined to form a keyboard 
identification number. The keyboards self-identify when the machine is 
turned on and when a new keyboard is attached. Keytioard returns the 
identification number of the keyboard currently attached. 

Function Keyboard: Keybdld; 

Functicm Le^fids: Keybdid; 

Keyboard identification numbers.- 

76543210 



Marajfacturer 



LaewiA 



LeoaTds 



Manufacturer: 

00 ~ APD (i.e., TKC) 

01 — 

10 ~ Keytronics 
Layout: 

00 ~ Old US (73 keys) 

01 — 

10 ~ European (77 keys) 

11 ~ Final US (76 keys) 



Layout/Legends 

$0F ~ Old US 

$26 — Swiss-Gei-man (proposed) 

$27 ~ Swiss-French (proposed) 

$29 — Portuguese (proposed) 

$29 ~ Spanish (proposed) 

$2 A — Danish (proposed) 

$2B ~ Swedish 

$2C ~ Italian 

$2D ~ French 

$2E ~ German 

$2F ~ UK 

$3C — APL (proposed) 

$3D ~ Canadian (proposed) 

$3E ~ US-Dvorak 

$3F ~ Final US 
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3.1L4^ Keyboard State — KeylsDown and KeyMap 

Low level access to the keyboard is provided through a pollable keyboard 
state. This state information is based on the physical keycodes defined 
above. KeylsDown returns the position of a single specified key. KeyMap 
returns a 128-bit map, one bit for each key. 

Function KeylsDown (key: KeyCap): Boolean; 

Rrocedure KeyNtap (var keys: KeyCapSet); 

A zero indicates the key is up, a one indicates down. For the mouse plug, a 
zei'o indicates unplugged, a one indicates plugged in. Certain keys are not 
pollable; the corresponding bits will always be zero. These keys are the 
diskette insertion switches, parallel port, and power switch. (The parallel 
port and mouse plug keys are unreliable across reboots on older hardware.) 

3.11J5 The Timers 

The timer procedures let you use either the microsecond timer or the 
millisecond timer. 

3-1L5.1 The Microsecond Timer — MicroTimer 

The MicroTimer function simulates a continuously running 32-bit counter 
which is incremented every microsecond. The timer is reset to each time 
the machine is booted. The timer changes sign about once every 35 minutes, 
and rolls over about every 70 minutes. 

FurKticm MicroTirrKir: Microseconds; 

The microsecond timer is designed for performance measurements. It has a 
resolution of 2 microseconds. Calling MicroTimer from Pascal takes about 
135 microseconds. Note that interrupt processing will have a major effect 
on microsecond timings. 

3.11.5J2 The Millisecond Timer — Timer 

The Timer function simulates a continuously running 32-bit counter which is 
incremented every millisecond. The timer is reset to each time the 
machine is booted. The timer changes sign about once every 25 days, and 
rolls over about every 7 weeks. 

Fiffiction Timer: MillisecofMJs; 

The millisecond timer is designed for timing user interactions such as mouse 
clicks and repeat keys. It can also be used for performance measurements, 
assuming that millisecond resolution is sufficient. 

3.11-6 Date »)d Time — DateTime, Sd;DateTime and DatteToTime 

The date and time procedures let you 

■ Set the current date and time. 
" Find out the date and time. 
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The current date and time are available as a set of 16-bit integers that 
represent the year, day, hour, minute and second, by calling DateTime and 
SetDateTinre. The date and time are based on the hardware clock/calendar. 
This restricts dates to the years 1980-1995. The clock/calendar continues to 
operate during soft power off, and for brief periods on battery backup if the 
machine is unplugged. If the clock/calendar hasn't been set since the last 
loss of battery power, the date and time will be midnight prior to January 1, 
1980. Setting the date and time also sets the time stamp described below. 
DateToTime converts a date and time to a time stajmp, defined in the next 
section. 

RrcNsoJure CMelime (var date: DateArray); 

Procedure SetDateTime (dafce: DateAnray); 

Psoc&dkKB DateToTime (date: DafceArray; var time: Seconds); 

3.11.7 Tirrw sa:amp — TimeStamp^ SetTirra^Star^ and TiriM^ToDate 

The current date and time are also available as a 32-bit unsigned integer 
which represents the number of seconds since the midnight prior to 1 
January 1901, by calling TimeStan^ and SetTiir^Stamp. The time stamp will 
roll over once every 135 years. Beware—for dates beyond the mid 1960's, 
the sign bit is set. The time stamp is based on the hardware clock/calendar. 
This clock continues to operate during soft power off. If the clock/calendar 
hasn't been set since the last loss of battery power, the date and time will 
be midnight prior to January 1, 1980. Setting the time stamp also sets the 
date and time described above. Since the date and time is restricted to 
1980-1995, the time stamp is also restricted to this range. TimeTcOate 
corwerts a time stamp to the date and time format defined above. 

The time stamp procedures let you 

■ Set the time stamp. 

■ Convert between standard date and time and the time stamp. 
Function TimeStamrfc Seconds; 

F^ocedire SetTimeStamp (time= Seconds]^ 

RrocedhA-e TimeToDafce (time: ^cond^ var date: DateArray); 
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The current date and time are available as a set of 16-bit integers that 
represent the year, day, hour, minute and second, by calling DateTiruHe and 
SetDateTime. The date and time are based on the hardware clock/calendar. 
This restricts dates to the years 19K)-1995. The clock/calendar continues to 
operate during soft power off, and for brief periods on battery backup if the 
machine is unplugged. If the clock/calendar hasn't been set since the last 
loss of battery power, the date and time will be midnight prior to January 1, 
19K). Setting the date and time also sets the time stamp described below. 
Dfll;eToTinne converts a date and time to a time stamp, defined in the next 
section. 

RroceGKjre DateTime (var date: Ddte^^a/); 

Prfx:eckjre SetDateTime (date: DaieArrayl!; 

Procechjre DafceToTime {dste: DaieAnray; var time: Seconds); 

3.11.7 Time Stmnp — TimeStamp, SetTirr^^arrv) and TinrwToDate 

The current date and time are also available as a 32-bit unsigned integer 
which represents the number of seconds since the midnight prior to 1 
January 1901, by calling TimeStarr^ and SetTimeStcmp. The time stamp will 
roll over once every 135 years. Beware— for dates beyond the mid 1960's, 
the sign bit is set. The time stamp is based on the hardware clock/calendar. 
This clock continues to op^-ate during soft power off. If the clock/calendar 
hasn't been set since the last loss of battery power, the date and time will 
be midnight prior to January 1, 1980. Setting the time stamp also sets the 
date and time described above. Since the date and time is restricted to 
1980-1995, the time stamp is also restricted to this range. TimeTdDaite 
converts a time stamp to the date and time format defined above. 

The time stamp procedures let you 

■ Set the time stamp. 

• Convert between standard date and time and the time stamp. 

Functia\ TimeStamp: SiMinrais; 

Procechf e SetTiiT»9;amp (time: Seconds); 

Procedure TimeToDate (time: Seconds; var date: DateArray); 
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Bringing Your Application 
to the Lisa Desktop 



4.1 Adding the USES List Bements 

Before bringing your application to the Lisa desktop you must add the 
required USES list elements to your MAIN program and any of your units. 
Depending on what kind of application you are porting^ you use different 
USES list elements. 

1. For text output only 

{$U OP/UCMJickPort} UQuickPort; 

2. For graphic (QuickDraw) and/or text output 
{$U OuickOraw) OuickDran, 

{$U OP/UOPoxtGraph} UQPortGraph; 

3. If you need to use Graf3D (order of list elements important) 
{$U OuickDraif} OuickDraw^ 

{$U 0P/Graf3D.OBJ} GrafSD, 

{$U QP/UOPortGraph} UQPortGraph; 

4. For graphic (QuickDraw) and/or text output, and the hardwsore interface 
{$U OuiddOraw} OuicicOraN, 

{$U QP/UOPortGraph} UQPortGraph, 
{$U QP/Hardware} Hardware; 

5. To use the VTIOO terminal emulator 
{$U QPAIQPortVTlOO} UQPortVTlOO; 

6. To use the Soroc terminal emulator 
{$U QP/UOPortSoroc} UQPortSoroc; 

7. If you are calling the additional QuickPort procedures (order of list 
elements important) 

{$U QuicicDraw} OuickDraif, 

{$U QP/UOPortCall} UQPortCall, 

{$U QPAiOuickPort} UQuickPort; {or UQPortGraph, 

UOPortVTlOO, 
UQPortSoroc} 
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Ul^ortCall^ unlike the other units^ is only an interface and contains no 
code. 

A2. System Confi^irafcion 

This section assumes that you are using a two-ProFile system to develop 
your QuickPort applications. The ProFile with the off ice system is called 
"office" in this discussion^ and the ProFile with the Workshop is called 
"workshop." In the Workshop, set the prefix to the workshop volume. If you 
have a Lisa 2/10 you will not need to set the prefixes as described in this 
section because all development will be done on one volume. 

There ai'e two different environments to consider: 

• The development environment. That is, the environment you use when 
developing a QuickPort application. The development environment is the 
Workshop. 

■ The run-time environment. This is the environment that the QuickPort 
application runs in. The run-time environment is the Office System. 

4.2.1 The Development EnPydronment 

When developing, you must 

» Boot from the Workshop. 

■ From the Workshop System Manager, set the prefix to the Workshop 
volume. 

• Place all files listed in the USES statement on the prefix volume. 
You must have the following files on your prefix volume: 

- QPAJQPortCaU 

- QP/UQPartGraph 

- QPAX?PoitSaroc 

- QP/UQPortVTlOO 

■ QPAJQuickPort 
> QP/Hardware 

- QP/Qraf 3D 

- QPUb.Obj 

- TKUb.Obj 

- TK2Ub.0bj 

- QP/Phrase 

The QuickPort exec file, c^/make, must be on the workshop ProFile. 
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4.2J2 The Run-Time Environment 

When running a QuickPort application^ you must 

• Boot from the office system. 

■ Have all the libraries your application needs on the office system 
volume. 

» Have TKLib-Obi TK2LitL0bx and QPLib.Obj on the office system 
volume. 

43 Generating Your Tool 

To generate your tool, you must run the QuickPort exec file, cyt/make, or 
customize cffi/make to compile, essemble, and link your tool. Qp/moke 
assumes all source files are in Pascal. You can customize Qp/make to 
assemble your files. Qp/make forces recompilation of all your application's 
units, compiles your application's main program, and then links your 
application's units with the QuickPort intrinsic units. Then qp/make assigns 
the tool name and creates the phrase file using the tool number in the file 
name. 

Qp/make renames the object code to a file name of the form: 

{T*^obj 

where ## is the tool number you specified when qp/mdce was invoked. 
Qp/m^e copies the phrase file to a file name of the form: 

{T*#}PHRASE 

If your application uses other support files, such as data files, rename the 
files using the {T*J^ tool number as the first part of the file name, e.g., 

{T##<}suppart 

Then, whenever a user selects the tool's icon from the desktop, all the files 
with the {T*Jj v/ill be copied or deleted. Qp/make assumes that the source 
files and libraries are on the prefix volume. Refer to System Configuration 
above for more information. 

Qp/m^e can be invoked in two ways, depending on how many units your 
application has, and depending on whether you need to specify additional 
object files that your application does not generate but needs to link to. If 
your application has four or fewer units and does not need to specify 
additional object files for linkingt, qp/make can be invoked as follows: 

Run <qp/m^e (mainprogpram, tool##, tool volume, unita^ wiitb, unite, 

unitcO 

where 

mairprc^am is the filename of your application's main program. 

tool ## is the tool number you want used in your 

application's tool name. We recommend you use 
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your Lisa's serial number plus an offset. Using the 
serial number plus an offset will fwevent duplication 
of tool numbers among different software 
developers. For testing you can use any number 
greater than 20. 

tool volume is the office disk name. The tool will be copied to 
the office system. 

unita, unitb Up to four units for your application. If you use 
unite, wiitd more than four units, use the alternate way to 
invoke qp/m^e as described below. 

If your application has more than four units, and/or needs additional units to 
link against, qp/rradke can be invoked as follows: 

Rjn <qpTi^e (mainprc^iram, tool#, tool uolunw, <., UnitList, OtherCMbijLJst) 

where 

mainpropram, tool 9, and tool volume are the same as above. 

UnitList is a file that contains the names of all your units. 

When you create your UnitList file, be sure to list 
the units in the order they should be compiled. 

OtherCKiJJst is a file that lists any object files that your 

application links against but you don't generate. 

Refer to some QuickPort examples programs (qp sample, note, text, and so 
forth) on the release diskette. 

4.4 Installing Your Tool 

After you run qp/make successfully, you must install the application on the 
Lisa desktop. This installation process creates a tool icon and stationery pad 
for your tool. To install a tool you run InstallTool from the Workshop. After 
InstallTool is finished, when you leave the Workshop and start the Office 
System, your tool and its stationery pad will be on the desktop. 

To install a tool, run InstallTool from the Workshop with the tool number you 
specified in qpm^e. 

Rjn what Progreum? InstallTool 

The InstallTool program will prompt you as follows: 

Please enter the nanw of the device your tool is on. [PARAPORT] 

This is the name of your Office System ProFile. 

Please enter your tool id number 

Enter the tool number you specified when you ran qp/make. 
Remember, ever^^ tool must hm,''e a unique numb&r. 

Does your tool crealte docwnents? (Y or hJ) [YES] 

If you answer no, a tool like the Calculator is created. In other 
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words, a tool that allows only one instance of itself at a time. 

Can your tool handle more than one document afc a time? IS you 
(kffi't know, press return. (Y or hO [NO] 

Some tools, such as LisaWrite, create one process that controls 
multiple documents. You must answer no for QuickPort tools. 

The stationery opening rectangle is defaulted to 10, 40, 640, 290 

These values are always the same. 

Do you wish to specify a diff ermt one? (Y or NO [NO] 

If you answer yes, you are prompted for the values for the size 
of the rectangle when a document is opened. This rectangle will 
be used whenever a document is opened. 

Please enter the name of ycnr tooL 

Every tool has a tool number and a tool name. When you enter a 
tool name, the install program places the tool name in the 
desktop names of the tool and its stationery. 

"Tool name" has \ixxsn sucessfully installed in U» Office System 
and it will a(^3«ar in the disk window associated with the device. 

After you've finished running the InstallTool program, boot the Office System. 
Your application's tool and stationery pad should be on the desktop. You 
only need to run InstallTcml once even if you regenerate your tool. If you do 
regenerate it, however, the tool name in the object file will be lost, and 
"Tool XX" will be listed in all the alerts. To get the tool name back in the 
alerts, you must run InstallTool again. 

4.3 The Icon Editor 

The icons created by the InstallTool program are blank (without pictures). If 
you want to design an icon for your application, contact Macintosh Technical 
Support. 

4.6 Shippir^ Yoajt ^^lication 

Your application's phrase file, as well as the object file, must be shipped. 
The phrase file contains the standard QuickPort menus and alerts, and it 
must be shipped with your application. 
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Appendix A 
The Standard QuickPort Menus 



A.1 File/Rrlnt Menu 

Set Aside Eveiything Returns all 
windows to their icons without saving 
the contents. 

Set Aside Vmv dcKiument" Returns the 
current document to its icon without 
saving the contents. 

Sawe & Put Away Saves the contents 
of the document, closes the window, 
terminates the program, and returns the 
icon to its original location. 

Save & Continue Saves the contents of 
the document and leaves the window 
open. 

Revert to Previous Version Always 
gray — not supported by QuickPort. 



Print As Is 

document. 



Prints one copy of the 



Formofc for Rrinter Sets formats in the 
document based on the printer that will 
be used. 

Print Prints the document using the 
settings from the Format for Printer 
dialog box. You may choose to print 
multiple copies. 

Monitor the Printer Shows the status 
of the document(s) being printed. 



Set Aside EKerything 

Set Rside "basic Paper 05/24" 



Sa/e & Put flM^ 
IstK & Continue 

Revet to ReMOUS KwsJon 



PrirA Rs is 
Format for Printer . 
Print ... 
Monitor the Printer 
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A.2 Edit Menu 

Copy Copies the current selection 
onto the Clipboard. In the text panel 
the selection is done as in LisaWrite. 
In the graphic panel, the entire panel is 
copied. If there is a text panel, and a 
graphic panel, you must use Select All 
Graph to make the selection. 

Read Input From Cliptioard Places 
what is in the Clipboard into the input 
buffer. 

Erase Erases the current selection. 

Satk/e &jrrer Saves the lines that 
scroll off the top of the screen area. 
A check next to Save Buffer indicates 
that the lines will be saved. 

Don't Sawe BuTfer Does not save the 
lines that scroll off the top of the 
screen area. A check next to Don't 
Save Buffer indicates that the lines 
will not be saved. 

Select All Text Selects all the text 
in the text panel when there is a text 
panel. 

Flusdi Input Clears the input panel. 
This command is shown only when the 
input panel is shown. 

Select All Graph Selects the entire 
graphic panel when there is a graphic 
panel. 

A.3 Terminal ^j^^ifics 

Set up Allows you to select K) or 
132 characters per line, and line 
wraparound. 

The following dialog box appears for 
you to fill in: 



HI 



cm 

Read Input From Clipboard 



Erase 

Sai«ieBuFFer 
vDont Sai/e BuFFer 



Seled: All Text 



afflfflffltfflHiMi^ 



Setup 

Shotr Tab Ruler 

Hitle T^ Riila- 



Desk File/Print Edit Terminal Specifics Execution Page Layout 



Characters Per Line 
lii-aparound 



80 n 132 
iYes DNo 



CZD 



Tab :0 



[ Cancel ] 
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Show Tab Ruler 

ruler. 



Displays the tab 



Hide Tab Ruler Hides the tab ruler. 



A.4 Execution 
Restart 



Restarts program execution. 



Resume Starts program execution at 
the point where it was suspended by an 
♦-period. 

A3 Page Layout 

Rreview Page Margins Shows the 
page margins. Note that the default 
page margins are such that the output 
in the text panel will not fit in the 
width of an 8" by 11" page. Before 
printing you should adjust the left and 
right margins ao that each vertical 
page will fit in one 8" by 11" page. 

Preview Page Breaks Shows the page 
breaks. 

Dont Rreview Pag^ Does not show 
the page boundaries. 

Set Horizontal Page Break Sets a 
horizontal page break at the position of 
the last mouse click. 

Set Vertical Page Break Sets a 
vertical page break at the position of 
the last mouse click. 

Clear All Manual Breaks Clears all 
the page breaks set in the document. 




•Prein&i' Page Margins 
Pvevitw Page Breaks 
Dont Previeir Pages 



Headings and Margins... 



Set Horizontal Page Break 
Set kiertical Page Bredk 
Clear All Manual Breaks 
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Writing Your Own 
Terminal Emulator 



B.1 Introduction 

This appendix briefly discusses how to write your own terminal emulator, 
using the standard terminal as a template. To write a terminal emulator, 
you must understand Clascal. Specifically, you must understand how to 
extend a Clascal program by creating a subclass, overriding existing methods, 
and creating new methods. This section assumes you are comfortable with 
these basic Clascal concepts. If you don't understand Clascal, contact 
Macintosh Technical Support for a copy of ^n Introduction to 
Clascal before reading this section. 

To write a terminal emulator, you create a subclass of TStdTerm. 
TStdTern is the standard terminal provided by QuickkPort. The subclass 
you create defines the terminal emulator you want. This appendix discusses 
TStdlera, the methods you must override in your subclass, and the methods 
used by TStdTerm. You can also add your own methods in your subclass. 

BJ2 TStdTerm 

TStdTexB is the standard terminal that is used by QuickPort applications 
unless the VTIOO, Soroc, or any other terminal emulator is specified. The 
TStdTem fields and methods are discussed in this section. 

a2.1 TStdTem Fields 

The fields you need to know about in TStdTcrn are listed below. These 
fields explain how the standard terminal behaves. You may want to change 
some or all of this behavior in your terminal emulates. 

naxLines The maximum number of lines in the window. 

naxColunns The maximum number of columns in the window. 

cursorshape The shape of the cursor. The standard terminal uses 

a box cursor. 

saveBuf fer To save lines as they scroll off the top of the screen 

into the buffer. 

wraparound BOOLEAN, whether wraparound is on or off. 

stopOutputKey Used to stop output. 

startOutputKey Used to start output. 

You can only chage these fileds in your a=?EATE method. 
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BSL2 TStffTern Methods You Must Ovenride 

You must override three of these four methods in your subclass. You may 
want to override CtrKeyWrite. 

B.2^.1 CREATE 

CREATE creates an object of class TStdTerm. You must override the 
CREATE method in your subclass. 

FUNCTION {TStdTemilCREATE (object.- TObject; heap : 

Theap) : TSTdTern; 

You must use object and heap as arguments in your CREATE method. 

BJL2J2 VHrite 

VMrite is called by QuickPort when the program calls a virite. You must 
override the VHrite method in your subclass to handle escape sequences that 
apply to your terminal. 

PROCEDURE {TStdTeiii}VWrite (VAR str : Tstr253); 

B:2.23 Vread 

Vread is called by QuickPort when the program calls a read. You must 
override the Vread method in your subclass to return any escape sequences 
generated from your terminal. 

PROCEDURE {TStdTem} Vread (VAR ach: char; VAR 
keycap : Byte; VAR applekey^ 
shiftkey, optionkey ; BOOLEAN); 

BJZJ2A CtrKeyWrite 

CtrKeyWrite handles the control keys for the terminal emulator. You 
should override this method in your subclass if you want to handle different 
control keys. 

PROCEDURE {TStdTem}CtrKeyWrite (ctrch: CHAR); 

The control keys handled in the standard terminal are CR (no LF), LF, Bell, 
Backspace, Horizontal Tab. 

B3 Procedures Terminal Emulafcors Can Call 

The procedures listed in this section can be called by any terminal 
emulators. Note that these are not methods and do not need to be 
overridden in your subclass. 

B3.1 Screen Control Ftocedures 

These procedures use escape sequences. 
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B3.1.1 Manipulating Lines — VGetLine and VPutLine 

VGetLine deletes the specified line. VPutLine inserts the line at the 
specified line number. 

PROCEDURE VGetLine (lineNo : INTEGER; VAR line : 
Tstr255; delete : BOOLEAN); 

PROCEDURE VPutLine (lineNo .- INTEGER; VAR line : 
Tstr255; insert : BOOLEAN); 

B3.12 Redrawing — RedrawScreen and RedrawLine 

RedrawScreen and RedrawLine are used after VGetLine and VPutLine. 

RedrawScreen repaints the entire screen after a change to the lines or a 
screen size change. RedrawLine repaints a line after its attributes have 
been changed. 

PROCEDURE RedrawScreen; 

PROCEDURE VPutLine (lineNo : INTEGER); 

B.3-1,3 Scrolling ~ VScr ol 1 Li nes 

VScrollLines scrolls output on the screen without changing the data 
structure. 

PFH3CEIXffiE VScrollLines (topRegion, bottomRegion : 
INTEGER; scrollhownanylines : 
INTEGER); 

A positive value for scrollhownanylines scrolls down. 

B3.1.4 Changing the number cT columns -- ChangeHaxColumns 

ChangeMaxColumns changes the maximum number of columns per line to the 
specified number. When ChangeHaxColunns is called, the corresponding 
character font is used. If the columns per line is 80 or less, QuickPort uses 
a 12-pitch font, otherwise a 20-pitch font is used. 

PROCEDURE ChangeMaxColunns (newColunns : INTEGER); 

B3.13 Changing Fonts — ChangeFont 

ChangeFont changes to the specified font. Because of cursor positioning, 
QuickPort supports only fixed pitch fonts. 

PROCEDURE ChangeFont (newFont : INTEGER); 

BL2.4 VStrWrite 

VStrWrite writes the string from the cursor position. This call is the one 
that does the actual display of output. Terminal emulators should call this 
after determining there is no escape sequence in the string. This call 
actually displays the output. No control functions are allowed in the string. 
This call handles wraparound. 

PROCEDURE VStrWrite (VAR str = Tstr255); 
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